Skip to content

Introducing the OINK implementation preview

OINK turns a directly customized Docsy codebase into a local-first, Hugo-only documentation theme with multilingual infrastructure and reusable content components.

Today we are publishing the OINK implementation preview: a directly evolved Docsy theme with one canonical product shell, a Hugo-only consumer build, local-first browser dependencies, a general multilingual framework, and a set of reusable content components drawn from PGSTY documentation sites.

This preview marks the implementation and documentation milestone ahead of the first tagged release and production Cloudflare Pages deployment.

Why OINK exists

Several mature documentation sites had independently copied the same Docsy layouts, navigation, search code, SCSS, JavaScript, and shortcodes. A common fix had to be repeated across repositories, while each site also carried a frontend toolchain and implicit network dependencies that made isolated builds harder than they needed to be.

OINK consolidates the genuinely reusable layer. Product matrices, portals, pricing pages, and other business-specific behavior stay in their own sites. The shared theme owns the documentation shell, browser runtimes, multilingual routing, accessibility behavior, and content-component contracts.

What changes

One product instead of a mode

OINK is not an optional skin. There is no oink.enabled flag, params.oink.* namespace, or parallel upstream-versus-brand template tree. The implementation in theme/ is the product.

That decision avoids two visual systems and two test matrices. Native Hugo settings and compatible Docsy parameters keep their established meanings.

Hugo-only consumer builds

A complete consuming site builds with:

hugo --gc --minify

Bootstrap, Font Awesome, fonts, search, diagrams, API documentation runtimes, and OINK components are committed with the theme. Node.js, npm, PostCSS, Autoprefixer, and CDN downloads are not consumer requirements.

Repository maintainers still use Node-based tools for tests and vendor refreshes. That maintenance toolchain is deliberately outside the public site-build contract.

Local-first browser behavior

The default starter serves its shell, fonts, icons, search, Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, and Infographic dependencies from the generated site. Optional runtimes are selected per page and loaded at most once.

PlantUML and Diagrams.net do not receive public service defaults. A site must configure a controlled endpoint, use a pre-rendered result, or make an explicit remote-service choice.

Multilingual infrastructure

Language routing comes from Hugo’s language and translation objects. One configured language hides the selector. With two or more languages, a click advances by configured weight, while a short hover or keyboard focus opens the complete menu. If the current page lacks a translation, the selector goes to the target-language home page instead of a dead path.

The starter and documentation site use English as the primary language and Simplified Chinese as the second. Every page in the core docs and blog scope has a colocated .zh.md translation with stable explicit heading IDs.

Reusable components

OINK adds theme-owned Asciinema, ECharts, Infographic, document carousel, details, tabs, cards, navigation cards, document cards, and parameter components. They generate unique instance IDs and load their local assets only when used.

ECharts accepts structured JSON or YAML plus optional JavaScript callbacks referenced as $fn:name. Callback code runs only on pages that declare it.

What stays familiar

OINK retains Docsy’s content organization, front matter, documentation and blog sections, menus, taxonomies, print output, repository links, common shortcodes, diagrams, API reference features, and extension hooks. Existing sites can remove duplicated common implementations without rewriting ordinary Markdown.

The project also preserves Docsy’s Apache-2.0 history and attribution. A vendor manifest records pinned third-party sources, licenses, artifacts, and checksums.

Try the starter

Setup instructions updated on 2026-10-17

This article records the original implementation preview. Use Hugo Extended 0.168.0 for setup and validation today; the baseline advances with stable releases. Older-Hugo compatibility testing and adaptation are discontinued.

Install Git, Go 1.27 or newer, and Hugo Extended 0.168.0, then evaluate the official Starter:

git clone https://github.com/pgsty/oink-starter.git my-docs
cd my-docs
hugo server

Update older Starter workflow pins to the same Hugo baseline. Open the local English and Chinese pages, switch languages, search locally, change color mode, and visit the component examples. For an isolated environment, follow the offline archive installation guide.

Current validation

The implementation includes automated coverage for:

  • Hugo Extended 0.168.0 builds;
  • forbidden consumer Node/npm/PostCSS/Autoprefixer paths;
  • LTR, RTL, subpath, print, color-mode, and production assets;
  • hidden, click-to-cycle, hover-menu, translation-fallback, and RTL language behavior;
  • local per-page runtimes and repeated component instances;
  • ECharts structured options and callback integration;
  • an offline bilingual starter and offline release archive;
  • vendor licenses and checksums;
  • non-mutating migration rehearsals for SILO, PGSTY, SOW, and Pigsty.

The latest four-site rehearsal built temporary copies of all four sites cleanly.

What remains before release

Before tagging the first public release, we will finalize the module and package identities, apply the initial version across source tags, archives, and documentation, and connect the production Cloudflare Pages deployment to the pinned Hugo baseline.