01 / ENGINEERING FIRST
Built for Engineers
◇ Ship docs, not build pipelines
- Production-ready from day one
- Full-text search, i18n, and versioning built in
- RSS, SEO, and Google Analytics ready
Focus on documentation, not site plumbing.
OINK 1.0 · Local-first · Hugo-only
PGSTY OINK
Markdown in. Modern docs out.
Knowledge Publishing Framework
Why OINK
Docs. Engineered.
Everything engineering docs need — built in, kept local, and loaded on demand.
02 / CLEAN BY DESIGN
Clean. Complete.
◇ Modern design. Proven foundation.
- User Experience inspired by Fumadocs & Hextra
- The powerful Hugo Docsy documentation feature set
- Look and feel tuned for open source and engineering teams
Quiet interface. Serious capability.
03 / LOCAL FIRST
Hugo. Nothing Else.
◇ Everything ships with the theme
- One hugo command builds everything
- No npm install. No PostCSS.
- All assets local. Fully offline.
One deterministic path from laptop to production.
build.sh
# one command, one deterministic output
$ hugo --gc --minify
✓ assets bundled locally
✓ multilingual routes built
✓ public/ ready to deploy
04 / EXTENSIBLE
Content. On Demand.
◇ First-class components, loaded per page
- Code Groups, FileTree, and Fields for everyday technical writing
- Gallery, Image Zoom, and diagrams for visual explanations
- Every component has semantic Markdown and print output, with JavaScript loaded only when interaction needs it
More expression. Zero baggage elsewhere.
Beyond docs
Six kinds of content, one shell
Documentation sites rarely stay documentation-only. The shapes that normally need a second tool share this one’s shell, search and outputs.
Documentation
Sidebar tree, page outline, breadcrumbs, pager, edit and history links — the shell every other content type reuses.
Blog and RSS
Dated posts, count-sorted tag panels, and a separate feed for each language.
Books
Chapter numbers, {#id num=} figures and equations, xref cross-references, and whole-book print.
Releases and downloads
One data/download/*.yaml becomes release cards, asset tables and checksums. Publication state is data.
Landing pages
Twenty-two server-rendered sections compose a page. The one you are reading is one of them.
API references
Swagger UI and Redoc as local runtimes. Keep the spec in the repository; it works offline.
Component reference
Twenty-one components, loaded on demand
Each component has its own page and a defined shape in HTML, print, Markdown and RSS. Interactive runtimes ship only on pages that use them.
ECharts
echarts data fence
Infographic
declarative data fence
Markmap
mind maps from headings
Asciinema
terminal casts, local player
PlantUML
UML through your own server
Draw.io
diagrams that stay editable
Mermaid
local diagram runtime
Math
KaTeX at build time
File trees
filetree data fence
Galleries
gallery data fence
Code blocks
Chroma · lines · copy · fold
Images
captions · sizing · zoom
Tables
captions · numbers · matrix
Fields
a table plus {.fields}
Callouts
> [!NOTE] · 10 types
Tabs
fences with {tab=}
Steps
a list plus {.steps}
Cards
a list plus {.cards}
Badges
inline status, five tones
Keys
key names and chords
Include
files, params, build notes
Cases
Fifteen sites, one family
English, Chinese and bilingual; distribution manuals, product docs, three books, a company page, an extension catalog and a two-page tool. Every card opens the live site; the Case library explains the content model behind each one.
pgsty.comPGSTY: the company behind Pigsty.
pigsty.ccPIGSTY: the Chinese home of the open-source PostgreSQL distribution.
pigsty.ioPIGSTY: the English home of the open-source PostgreSQL distribution.
silo.pgsty.comSILO: the community-maintained MinIO fork for S3-compatible object storage.
oink.pgsty.comOINK: the Hugo theme every site in this library is built with.
caps.vonng.comCapsLock: turn the most useless key on the keyboard into a fifth modifier.
pig.pgsty.comPIG: the package manager that installs any PostgreSQL extension.
sow.pgsty.comSOW: the repository manager that builds and mirrors APT and YUM software repositories.
exp.pgsty.comPG Exporter: the Prometheus metrics exporter for PostgreSQL and Pgbouncer.
ddia.vonng.comDDIA: the Chinese edition of Designing Data-Intensive Applications.
tpme.vonng.comTPME: the Chinese edition of The Product-Minded Engineer.
pgint.vonng.comPG Internals: the Chinese edition of PostgreSQL Internals.
pgsql.ccPGSQL.CC: an operations library for PostgreSQL and the components around it.
pgsty.proPIGSTY PRO: the enterprise edition of Pigsty.
ext.pgsty.comPGEXT: the PostgreSQL extension catalog.
Before you commit
Questions worth asking first
Do I need Node.js, npm or a bundler anywhere?
No. The build dependency is Hugo Extended (0.160.1 or newer). Go is used once, to resolve the theme as a Hugo module; an offline archive or a Git submodule works without it. Interactive features still run JavaScript, but those scripts ship with the theme and attach only to the pages that use them.
I have a Docsy site. How hard is the move?
Content and front matter mostly carry over; the shell, navigation, search and components are replaced. Renamed keys fail the build with the new name, and bin/migrations/oink06.py reports what it would rewrite before it writes anything. Read Upgrade and migration.
Is OINK only for large documentation trees?
No. The example sites run from a two-page project site to a fifteen-hundred-file distribution manual, and one uses OINK for landing pages alone. The shell scales down as well as up.
How does it handle Chinese and other non-Latin content?
Local search uses Lunr for Latin scripts and a substring fallback for CJK, so those pages are searchable without a hosted service. English, Simplified Chinese (zh-cn, zh) and Traditional Chinese (zh-tw) interface text is human-reviewed; 28 more locales share the same key schema. RTL layouts are supported.
What do AI assistants and crawlers get?
With markdown in outputs, every page has an index.md sibling announced by rel="alternate", and the LLMS format writes a site-level llms.txt. The “open in ChatGPT / Claude” page actions exist but are off by default, because they hand the reader’s URL to a third party.
What is the license, and where does Docsy stand?
Apache License 2.0. OINK is a fork of Docsy that evolved independently; Docsy’s history, attribution and Apache-2.0 obligations are preserved, and every vendored runtime is listed with its license in VENDOR.json. See License and acknowledgements.
Start from a repository that already works.Use OINK Starter, replace the identity and content, then publish with a warning-strict Hugo build.