About on OINK

Example sites

Mon, 01 Jan 0001 00:00:00 +0000

OINK provides examples at three different scales. Choose the smallest one that answers the question you are investigating; the complete project site is useful for regression coverage, but it is deliberately larger than a normal consumer.

Choose an example

Example	Best for	Repository or guide
Bilingual project site	Production-scale configuration and QA	`pgsty/oink.pgsty.com`
Theme `exampleSite/`	Landing-page composition and theme checkout	`pgsty/oink/exampleSite`
Minimal bilingual consumer	Starting a new documentation site	Create a new site

Bilingual project site

The pgsty/oink.pgsty.com repository is the complete documentation and regression site you are reading. It keeps English and Simplified Chinese content side by side, pins the published Oink module in go.mod, and exercises documentation, blog, search, print, rich content, metadata, and responsive navigation.

Local-first operation

Mon, 01 Jan 0001 00:00:00 +0000

OINK’s local-first rule is simple: a feature owned by the theme must not silently depend on a public CDN, a build-time download, or an unconfigured public service. A complete distribution can be built and its core pages browsed inside a network-isolated environment.

What local-first covers

The theme serves these dependencies from the generated site:

Capability	Local delivery
Shell and responsive UI	Bootstrap and OINK CSS/JavaScript
Icons and fonts	Font Awesome, Open Sans, Chakra Petch, IBM Plex Mono
Search	Lunr plus a CJK substring fallback and per-language indexes
Diagrams and formulae	Mermaid, KaTeX, and Markmap
API documentation	Swagger UI and Redoc
Rich content	Asciinema, ECharts, Infographic, and carousel runtime

Assets are committed under assets/ or static/. Hugo publishes them under the site’s baseURL, including subpath deployments.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Oink is a direct Hugo theme, not an application server or a runtime wrapper around Docsy. Hugo resolves content, configuration, layouts, and assets at build time, then emits a static site for any ordinary file host.

System boundary

flowchart LR
  C[Site content] --> H[Hugo Extended]
  G[Hugo configuration] --> H
  T[Oink Hugo Module] --> H
  V[Committed third-party assets] --> T
  H --> P[Static public directory]
  P --> B[Browser]

The consumer boundary starts with a site plus the resolved theme module and ends with Hugo’s static output. No JavaScript package manager, CSS postprocessor executable, or remote asset download is required in that path.

Contribution guidelines

Mon, 01 Jan 0001 00:00:00 +0000

OINK is an independent theme derived from Docsy. Contributions must preserve the Apache-2.0 history and applicable third-party notices while improving the single canonical implementation.

Before opening a change

Search existing issues and pull requests in the OINK repository.
For a bug, record the Hugo version, installation mode, language, route, production command, and smallest reproducible input.
For a feature, explain why it belongs in the reusable theme rather than in a consuming site’s business layer.
Do not introduce an oink.enabled switch, an oink.* configuration tree, or a parallel visual shell. OINK’s standard layouts are the product.

Small fixes can go directly to implementation. Larger behavior changes should state their compatibility, offline, accessibility, security, and migration impact before code is written.

Open-source licenses and acknowledgements

Mon, 01 Jan 0001 00:00:00 +0000

OINK combines an Apache-licensed theme, a separately licensed documentation site, and third-party components that retain their own licenses. These layers are intentionally not relicensed as one undifferentiated work.

This page is a practical provenance guide, not a substitute for the license texts. When the summary and a license file differ, the license file controls.

License map

Surface	License	Authoritative record
Oink theme source and Oink theme changes	Apache License 2.0	Theme `LICENSE` and `NOTICE`
Site code, build tooling, and Docsy-derived material	Apache License 2.0	Site `LICENSE` and `NOTICE`
Original Oink documentation, unless noted otherwise	Creative Commons Attribution 4.0 International	`LICENSE-CC-BY-4.0` and the page or asset’s own attribution
Browser libraries, fonts, icons, and other bundled assets	Each component’s own license	Theme `VENDOR.json` and the license files distributed beside the assets

The Creative Commons license applies to original documentation content, not to theme code, copied source code, trademarks, screenshots, or third-party assets that carry a different notice. Likewise, Apache-2.0 on the theme does not replace a bundled dependency’s license.

About Oink

Mon, 01 Jan 0001 00:00:00 +0000

OINK turns Markdown, configuration, and local assets into a complete technical documentation site. With the theme source and Hugo Extended, a site can build documentation, a blog, multilingual navigation, local search, diagrams, API references, and reusable content components without maintaining a frontend toolchain.

What Oink provides

Capability	Theme contract
Documentation and blog layouts	Responsive navigation, breadcrumbs, table of contents, page metadata, feedback, print output, and content indexes
Multilingual behavior	Translated-page routing, language metadata, stable anchors, and per-language local search
Local-first browser features	Versioned styles, fonts, search, diagrams, API references, recordings, charts, and infographics
Content components	Tabs, details, steps, cards, carousels, diagrams, terminal recordings, charts, and parameter substitution
Reproducible delivery	A Hugo-only consumer build, pinned assets, an auditable vendor manifest, and regression fixtures

OINK evolves Docsy’s mature Hugo content model into one independent theme. It uses Hugo as its build platform and takes design inspiration from Fumadocs. The open-source licenses page records those relationships and keeps upstream lineage, inspiration, dependencies, and licensing distinct.