OINK

OINK is an open-source, Apache-2.0 Hugo theme that converts native Markdown content into a complete knowledge-publishing website, with Docs, Blog, Book, and OpenAPI shells, in a single Hugo Extended build.

What is OINK?

OINK is a documentation theme for Hugo Extended 0.160.1 or newer, maintained by the pgsty team and hosted at github.com/pgsty/oink. It receives Markdown pages, Hugo front matter, and a module import in the site config, then renders HTML for readers, RSS and Print for publication, semantic Markdown for reuse, and optional llms.txt, llms-full.txt, and navigation.json indexes for agents. The theme is derived from Docsy but is now a separate implementation: OINK owns its own Docs, Blog, Book, Swagger, and landing shells and does not run Docsy's Node/PostCSS pipeline.

What makes OINK stand out?

OINK emphasizes a local-first toolchain and native Markdown authoring without a JavaScript frontend build. Consumers do not need Node.js, npm, PostCSS, or a CDN, and a normal build makes no remote asset fetch.

• One deterministic toolchain — Resolve OINK as a Hugo Module once, then build and preview with a single hugo binary plus Go 1.27+ for module resolution.
• Complete publishing surfaces — Docs, Blog, Book, Swagger/Redoc, releases, downloads, and data-driven landing pages share one navigation and visual system.
• Native Markdown authoring — Tables, fenced code, lists, and attributes become tabs, steps, cards, fields, galleries, callouts, diagrams (Mermaid, PlantUML, Draw.io, Markmap), mathematics (KaTeX), and charts (ECharts) without MDX.
• Local-first delivery — Search, fonts, icons, syntax highlighting, and interactive runtimes are vendored; no CDN is used.
• Multilingual by design — Language-aware routing, translated-page peers, RTL support, and localized search; interface text covers 31 Docsy locale names and generic zh, each with CLDR plural forms.
• Progressive by default — Server-rendered content remains useful without JavaScript, while interaction, accessibility, responsive behavior, print, and machine-readable outputs are tested as separate contracts.
• Agent-ready outputs — Publication can emit LLMS, LLMSFULL, and NAVJSON indexes plus Book manifest for navigation by AI tools.

Who should use OINK?

OINK suits technical audiences who already write in Markdown and want a deterministic documentation build.

• Engineering documentation teams — Publish large product docs, API references, and tutorials with shared sidebars, breadcrumbs, version menus, and local full-text search.
• Open-source maintainers — Ship project documentation, blog, releases, and downloads in one repository, with no Node.js requirement for contributors.
• Multilingual product teams — Run English, Chinese, French, or larger locale sets with RTL support and localized search across one docs tree.
• Book and course authors — Use the Book shell to publish multi-edition, multilingual books with numbering and cross-references.

Use cases

• Product API portals: Add OpenAPI specifications via a Swagger/Redoc shell alongside surrounding guides and versioned changelogs.
• Corporate engineering sites: Compose bilingual sites with data-driven landing pages and a blog on a compact shared codebase.
• AI-ready knowledge bases: Emit llms.txt and navigation.json so search engines and agents can index the same content served to human readers.
• Technical e-books: Produce numbered, cross-referenced multi-edition books in the Book shell with print output.

How does OINK work?

The recommended start is the pgsty/oink-starter template, which pins a tested OINK release and includes GitHub Pages and Cloudflare Pages workflows. After cloning that starter, run hugo server and replace the site identity, home-page data, and sample content. Existing Hugo sites can instead run hugo mod init and hugo mod get github.com/pgsty/oink@latest, then import the module in hugo.yaml along with required Goldmark renderer settings.

Alternatives

OINK counts Docsy as its upstream: OINK forked Docsy's content model but now differs architecturally by owning its own UI shells and dropping the Node/PostCSS pipeline. Hextra and Fumadocs are other documentation-theme projects that can fill similar roles.

FAQ

Does OINK require Node.js?

No. OINK builds and runs with Hugo Extended only; no Node.js, npm, PostCSS, or CDN is required for consumer sites.

What Hugo version do I need?

Hugo Extended 0.160.1 or newer. The oink-starter template currently expects Hugo Extended 0.165.0, and CI pins 0.165.0.

Is OINK free?

Yes, OINK is licensed under Apache License 2.0 and derived from Docsy, with upstream attribution in a NOTICE file.

Can I migrate from Docsy?

Yes, a dedicated upgrade and migration guide exists at oink.pgsty.com/docs/admin/upgrade/. Existing Docsy sites should follow that guide rather than assuming drop-in compatibility, because navigation, config, front matter, and extension contracts differ deliberately.