Open. Indexed. Navigable. Knowledge.
A local-first Hugo theme for engineering documentation.

Get started · OINK Starter · Components · Live cases · Design

OINK turns native Markdown into a complete knowledge-publishing site with one Hugo Extended build. Its fonts, icons, search, diagrams, and feature runtimes ship locally and load only where they are used. Consumer sites need no Node.js, npm, PostCSS, bundler, or CDN.

The same content can serve people and tools: responsive HTML for readers, print and RSS for publication, semantic Markdown for reuse, and optional llms.txt, llms-full.txt, and navigation.json indexes for agents.

Why OINK

• One deterministic toolchain. Resolve the Hugo Module once, then build and preview with one hugo binary.
• Complete publishing surfaces. Docs, Blog, Book, OpenAPI, 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, diagrams, mathematics, charts, and API references without introducing MDX.
• Local-first delivery. Search, fonts, icons, syntax highlighting, and interactive runtimes are vendored; a normal build performs no remote asset fetch.
• Multilingual by design. Language-aware routing, translated-page peers, RTL support, alternate-site links, and localized search work across large documentation trees.
• Progressive by default. Server-rendered content remains useful without JavaScript; interaction, accessibility, responsive behavior, print, and machine-readable outputs are tested as separate contracts.

Start a site

Use OINK Starter

The recommended path is the public pgsty/oink-starter template. It is a small production baseline with Docs, Blog, Book, English/Chinese/French profiles, and GitHub Pages and Cloudflare Pages workflows—without this theme repository's internal fixtures.

Use this template on GitHub · Live starter · Setup guide

The current starter expects Git, Go 1.27 or newer, and Hugo Extended 0.165.0 or newer; it does not require Node.js. To evaluate the neutral template locally:

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

Open http://localhost:1313/. Replace the site identity, home-page data, and sample content in that order; the starter already pins a tested OINK release and includes a warning-strict production build.

Add OINK to an existing Hugo site

OINK is a Hugo Module. A site that does not already use modules can initialize one and resolve the latest release with:

hugo mod init github.com/example/docs
hugo mod get github.com/pgsty/oink@latest

Import the module in the site's root hugo.yaml:

module:
  imports:
    - path: github.com/pgsty/oink

# Hugo does not merge a theme module's Goldmark settings into the site.
markup:
  goldmark:
    renderer:
      unsafe: true
    parser:
      wrapStandAloneImageWithinParagraph: false
      attribute:
        block: true

Those Goldmark settings enable OINK's native container shortcodes, block-image attributes, steps, fields, captions, and numbered Book targets. Select the HTML, RSS, Print, Markdown, LLMS, LLMSFULL, and NAVJSON outputs the site needs; the configuration reference documents their defaults and scope.

For production, commit go.mod and go.sum, build with warnings promoted to errors, and inspect representative routes:

hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings --panicOnWarning

See Get started for repository structure, language profiles, customization, and deployment. Existing Docsy sites should also read the upgrade and migration guide.

What ships with the theme

Area	Included capabilities
Reading shells	Docs, Blog, Book, Swagger/Redoc, releases, downloads, Print
Navigation	Sidebars, breadcrumbs, TOC rail, pager, version and language menus
Discovery	Local full-text search, command palette, taxonomies, backlinks
Authoring	Code, tabs, steps, cards, fields, images, galleries, callouts, includes
Technical content	Mermaid, PlantUML, Draw.io, Markmap, ECharts, KaTeX, Asciinema
Landing pages	22 server-rendered sections with progressive enhancement
Outputs	HTML, RSS, Print, Markdown, LLMS, LLMSFULL, NAVJSON, Book manifest
Operations	SEO, analytics hooks, Giscus, feedback events, sharing, deployment-safe URLs

Interactive features remain opt-in where they express site policy. The theme provides the implementation; the consuming site decides which outputs, analytics, comments, feedback, assistant links, and image behavior to enable.

Live sites

OINK is exercised by fifteen real sites, from a two-page utility to large documentation estates and multi-edition books. These are representative:

Site	Shape	Case study
pigsty.io / pigsty.cc	Large English and Chinese documentation, blog, catalogue, and landing pages	EN · ZH
silo.pgsty.com	Large bilingual migration with manifest-generated navigation	SILO
pgsty.com	Compact bilingual corporate and landing-page site	PGSTY
ddia.vonng.com	Multi-edition, multilingual Book with numbering and cross-references	DDIA
tpme.vonng.com	Focused bilingual Book publication	TPME
ext.pgsty.com	Data-driven PostgreSQL extension catalogue	PGEXT
exp.pgsty.com	Bilingual product docs with a structured metrics catalogue	PG Exporter
caps.vonng.com	Two-page bilingual project with an interactive configurator	CapsLock

Browse all case studies.

Documentation

Guide	Purpose
Get started	Install, understand the repository, and establish a working baseline
Authoring	Write Docs, Blog, Book, release, and OpenAPI content
Components	Source-first examples and parameter references
Customization	Brand, navigation, layout, languages, search, outputs, and integrations
Operations	Preview, deploy, upgrade, troubleshoot, analytics, and SEO
Design	Maintainer contracts, decisions, research, and active proposals
Write Beautiful Docs	End-to-end tutorial in OINK's Book shell

The public documentation and regression site lives in pgsty/oink.pgsty.com. This theme repository owns implementation, defaults, vendored assets, focused checkers, and the narrow internal fixture under tests/site/.

OINK and Docsy

OINK began from Docsy's mature Hugo content model and remains Apache-2.0 with explicit upstream attribution. It is now a separate theme rather than a Docsy skin: OINK owns its Docs, Blog, Book, Swagger, and Landing shells; local search and command palette; native-Markdown component model; responsive and accessibility behavior; and reader, print, Markdown, and agent-facing outputs.

That difference is architectural as well as visual. OINK consumer sites do not run Docsy's Node/PostCSS pipeline, and OINK changes navigation, configuration, front matter, and extension contracts deliberately. Use the migration guide instead of assuming drop-in compatibility.

Compatibility

Dependency	Policy
Hugo	Extended 0.160.1 or newer; CI currently pins 0.165.0
Go	1.27 or newer for Hugo Module resolution; not needed when using an offline archive or submodule
Node.js	Not required to build or run an OINK site
Locales	Reviewed OINK interface text for English, Simplified Chinese, and Traditional Chinese; inherited Docsy locales retain English fallback for newer labels

Community and releases

Releases · Changelog · Issues · Discussions

A local build, a committed change, a public tag, a consumer dependency update, and a deployed site are separate release states. Pin a release tag for production and verify the public routes after deployment.

License

OINK is licensed under the Apache License 2.0 and derived from Docsy. See NOTICE for upstream attribution and VENDOR.json for bundled third-party components.