What is OINK
OINK is a standalone Hugo theme for medium and large technical documentation sites. It evolved from Docsy, retaining the content model and multilingual behavior while replacing the shell, navigation, search, and content components.
The current release is OINK v1.5.1, built with Hugo Extended 0.168.0 (with its built-in Sass compiler), plus Go when resolving the theme as a Hugo Module. No Node.js, npm, PostCSS, or CDN requests are needed: Bootstrap, Font Awesome, fonts, local search, diagram runtimes, and API reference runtimes all ship in the theme repository and load only on pages that use them.
Components are written in clean Markdown rather than a custom template
language: > [!NOTE] creates a callout, a table followed by {.fields}
renders as a parameter list, and an image followed by {caption="..."} becomes
a captioned figure. Fifteen production sites run on
OINK today, including this one.
What the theme provides
- The documentation and blog shell provides navigation, a sidebar tree, a table of contents, breadcrumbs, a pager, dark mode, print view, and accessible interaction.
- The multilingual structure provides translation routing, fallback for untranslated pages, language weighting, RTL, 32 complete interface catalogs, and an opt-in duo view (
params.ui.compare: true) for side-by-side reading. - Local browser features include Mermaid, Markmap, Swagger UI, Redoc, Asciinema, ECharts, Infographic, and full-text search. Mathematics is rendered by Hugo at build time and uses local KaTeX styles.
- Content components include callouts, tabs, steps, cards, field lists, file trees, galleries, badges, keys, and more. Most have a native Markdown form.
- Additional content types provide built-in book numbering and cross-references, release and download pages, data-driven landing pages, and OpenAPI reference pages.
The theme does not handle source hosting or deployment. A site can use GitHub, GitLab, or a private Git server. You can publish Hugo’s static output anywhere. The site owns its content, brand, and business components. The theme supplies the shell and reusable components.
Is OINK for me
| A good fit when | A poor fit when |
|---|---|
| The site has many pages and combines documentation, a blog, a book, release pages, and an API reference | The site has one or two pages and needs no structured navigation. A README or a lighter Hugo theme is simpler |
| You need full multilingual support rather than only a translation link on an English site | The site is mostly application UI. OINK can provide its documentation. Business components remain at the site layer |
| Reproducible builds and network isolation matter, and the build machine has no outbound access | You need interactive components inside the prose (React / MDX) |
| Several sites need a shared shell without copies of layouts and shortcodes | You want one switch to change the appearance. The theme has no brand switch. Appearance changes require CSS tokens and partial overrides |
| The team has no front-end engineers and maintains no Node toolchain | You need a built-in CMS or a WYSIWYG editor |
How it differs from other documentation systems
Choose a toolchain and authoring model before comparing individual features. Different systems can suit the same project. The choice depends on who maintains it:
| Your priority | What to evaluate |
|---|---|
| Keep an existing Hugo content workflow | Compare OINK with Docsy and Hextra using your own content tree, overrides, and language needs |
| Build without a Node toolchain | OINK includes browser assets in the theme. Hugo Module installation still needs Go to resolve modules |
| Write React components inside documentation | Evaluate an MDX-based system such as Docusaurus. OINK’s main authoring model uses Markdown, attributes, and shortcodes |
| Publish books, downloads, or data-driven landing pages | Try OINK’s built-in patterns on one representative page before adopting them site-wide |
Check each candidate’s current installation and extension documentation. OINK’s
search, image zoom, comments, and feedback require explicit configuration. The
site also selects Markdown and agent outputs under outputs.
OINK forked from Docsy and evolved as a separate theme. It retains Docsy’s source history, Apache-2.0 obligations, and attribution. For details, see License and acknowledgements.
Start here
- Get started — Use the official Starter. Customize one part at a time, then publish it.
- Components — Each component has one page. The source appears first, followed by the rendered result.
- Showcase — See fifteen production sites and the OINK features each site uses.
Highlights lists each theme capability. Each entry links to its guide.
To report a problem or submit a correction, follow the contribution guide. The 1.5.1 release notes cover Duo View repairs, output correctness, responsive reading, and the current build requirements.
Compare OINK with an ordinary Hugo theme. Each feature links to its guide.
Find the OINK production case closest to your documentation, book, landing page, or interactive tool.
The theme uses Apache-2.0. The documentation uses CC BY 4.0. Each bundled third-party runtime keeps its own license terms.
Where to report bugs and contribute theme changes, documentation, translations, and regression tests for OINK 1.5.1.