Welcome to OINK

• 1: About Oink
  • 1.1: Example sites
  • 1.2: Local-first operation
  • 1.3: Architecture
  • 1.4: Contribution guidelines
  • 1.5: Release process
  • 1.6: Open-source licenses and acknowledgements
• 2: Get Started
  • 2.1: Before you begin
  • 2.2: Install Oink
  • 2.3: Create a new site
  • 2.4: Basic site configuration
  • 2.5: Inspect the bilingual project site
  • 2.6: Run OINK in a container
  • 2.7: Other setup options
  • 2.8: Troubleshooting and known issues
• 3: Authoring
  • 3.1: Configuration
  • 3.2: Adding content
  • 3.3: Organize your content
  • 3.4: Hugo authoring tips
  • 3.5: Navigation and menus
  • 3.6: Look and feel
  • 3.7: Code blocks and Code Groups
  • 3.8: Logos and images
  • 3.9: Shortcodes
  • 3.10: Content components
    • 3.10.1: Badge
    • 3.10.2: Kbd
    • 3.10.3: Fields and Field
    • 3.10.4: FileTree
    • 3.10.5: Image Zoom
    • 3.10.6: Gallery
  • 3.11: Diagrams and formulae
  • 3.12: Taxonomy support
• 4: Advanced
  • 4.1: Multi-language support
  • 4.2: Search
  • 4.3: Versioning
  • 4.4: Advanced customization
  • 4.5: Apache ECharts
    • 4.5.1: ECharts gallery
    • 4.5.2: ECharts callbacks and trusted code
  • 4.6: Infographics with AntV
    • 4.6.1: Processes, timelines, and cycles
    • 4.6.2: Infographic layouts, funnels, and themes
  • 4.7: Comments with giscus
  • 4.8: Analytics, user feedback, and SEO
  • 4.9: Repository links and page information
  • 4.10: AI-agent support
  • 4.11: Print support
• 5: Deployment
  • 5.1: Serving your site locally
  • 5.2: Deployment on GitHub Pages
  • 5.3: Deployment on Cloudflare Pages
  • 5.4: Deployment on Netlify
  • 5.5: Deployment with Amazon S3 and CloudFront
• 6: Upgrade
  • 6.1: Upgrade the Oink Hugo Module
  • 6.2: Upgrade an Oink Git submodule or clone
  • 6.3: Migrate from the Docsy npm package
  • 6.4: Migrate an existing Docsy site

1 - About Oink

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

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.

Explore the project

The About section follows the lifecycle from evaluation through maintenance:

1. Example sites shows the full bilingual project site, the small theme example, and the guide for creating a minimal consumer.
2. Local-first operation defines which build and browser capabilities work without hidden network access.
3. Architecture explains the repository, build, page-shell, runtime, and extension boundaries.
4. Contribution guidelines covers theme and bilingual documentation changes.
5. Release process separates source completion, validation, public release, documentation updates, and hosted deployment.
6. Open-source licenses explains provenance, dependencies, acknowledgements, and the licenses for the site and theme.

Repository boundaries

The published Hugo Module is github.com/pgsty/oink. Documentation, examples, and regression tests live in the independent github.com/pgsty/oink.pgsty.com repository. Production consumers should pin a released tag or an immutable commit.

Site-specific content, branding, configuration, and business components remain under site control. General-purpose layouts, reusable components, local browser runtimes, and translations belong in the theme.

Start here

• Install Oink or create a bilingual site.
• Review the content authoring guide and advanced features.
• Read the implementation diary for design decisions and verification evidence.

A successful local build proves that one source tree renders in one local environment. It does not prove that a theme tag is public or that the hosted site contains the same commit.

1.1 - Example sites

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

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.

Clone and preview the published module path with Hugo:

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

Create the production artifact with:

hugo --gc --minify

Node.js and npm are maintenance dependencies for this repository’s formatting, translation, link, browser, and regression checks. They are not Oink consumer build requirements.

Theme example site

The theme repository contains a deliberately small exampleSite/. It exercises the checked-out theme directly and demonstrates a composable landing page without importing the project site’s documentation or npm workspace.

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

Use this example when changing landing-page data or checking a theme checkout. Use the bilingual project site when testing documentation navigation, translations, local search, rich components, or release behavior.

Build a minimal consumer

Follow Create a new site to assemble a small bilingual consumer from an empty directory. The guide creates the module pin, configuration, content tree, and first preview explicitly, so readers can see every required file instead of depending on a copied starter that may drift.

Related references include:

• Architecture for repository and build boundaries;
• Content components for reusable authoring primitives;
• Multi-language support for colocated translations and stable anchors;
• Deployment for artifacts, static hosts, acceptance checks, and rollback;
• Migration for moving an existing Docsy consumer to Oink.

Verify the right layer

A local preview proves that one checkout renders. It does not prove that a theme tag is public, a deployment contains the same commit, or the hosted route works. Record source, build, release, and hosted verification separately when using an example as evidence.

1.2 - Local-first operation

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:

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

What local-first does not cover

OINK cannot make arbitrary authored content offline. The following remain explicit network choices:

• external links, remote images, video, iframes, and API specifications;
• hosted search such as Algolia or Google CSE;
• analytics, comments, identity providers, and other SaaS integrations;
• PlantUML or Diagrams.net when an author chooses a remote renderer.

A page using one of these features can still be valid, but the site should not claim that page is fully available offline.

Service-backed diagrams

PlantUML and Diagrams.net differ from browser libraries: their normal workflows depend on a rendering or editing service. OINK therefore has no implicit public endpoint.

Enabling PlantUML without params.plantuml.svg_image_url, or Diagrams.net without params.drawio.drawio_server, fails the build with an actionable message. Configure a controlled local endpoint, publish a pre-rendered image, or make a deliberate remote-service choice:

params:
  plantuml:
    enable: true
    svg: true
    svg_image_url: https://diagrams.internal.example/plantuml/svg/
  drawio:
    enable: true
    drawio_server: https://diagrams.internal.example/

The OINK documentation regression site explicitly configures public demo servers so inherited diagram examples continue to render. That sample-site choice is not the theme default and should not be copied into an air-gap site.

Local search

Set:

params:
  offlineSearch: true

Hugo generates a search index for each language. The browser uses local Lunr search for Latin-script queries and a local substring fallback for CJK text. No query leaves the site.

Keep search useful by writing descriptive titles and summaries, setting the correct page language, and excluding generated or sensitive pages that should not enter a public client-side index. A local index is downloadable by every visitor and is not an access-control mechanism.

Per-page assets

OINK does not place every runtime on every page. Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, Infographic, and the carousel are selected from page feature markers. A page that does not use a component does not receive that component’s runtime.

When a page contains several instances of the same component, the runtime is still included once. Production resources are fingerprinted where the Hugo pipeline permits it, which supports integrity metadata and long-lived caching.

Third-party provenance

VENDOR.json is the machine-readable inventory for bundled dependencies. For each dependency it records:

• name and pinned version;
• original source;
• applicable license files;
• selected artifact paths and SHA-256 values;
• the maintainer update procedure.

The theme retains the corresponding license files beside vendor assets. Updating a runtime means refreshing the artifact, its license and notice material, its checksum, and its tests as one reviewable change.

Prepare an offline archive

Prepare the archive on a connected, trusted machine from an immutable Oink tag. For example:

git clone --branch vX.Y.Z --depth 1 https://github.com/pgsty/oink.git oink
git -C oink archive --format=tar.gz --prefix=oink/ \
  --output=../oink-vX.Y.Z.tar.gz vX.Y.Z
shasum -a 256 oink-vX.Y.Z.tar.gz > oink-vX.Y.Z.tar.gz.sha256

Transfer both files into the isolated environment, verify the checksum, and extract the conventional theme:

shasum -a 256 -c oink-vX.Y.Z.tar.gz.sha256
mkdir -p product-docs/themes
tar -xzf oink-vX.Y.Z.tar.gz -C product-docs/themes

Then configure the isolated site to use it:

theme: oink

The archive must include go.mod, hugo.yaml, layouts, assets, static files, translations, LICENSE, NOTICE, and VENDOR.json. Inspect it before relying on it in a disconnected build. If a future release publishes an archive and checksum, verify those published artifacts independently instead of assuming that every tag has attached files.

Verify an isolated site

A meaningful air-gap acceptance test covers both build time and browser time:

1. start with the verified theme archive and an empty Hugo cache;
2. block outbound HTTP, HTTPS, and Go module proxies;
3. run the production Hugo command;
4. browse English and Chinese pages from the generated output;
5. exercise search, dark mode, diagrams, API docs, and content components;
6. inspect every HTML and CSS subresource URL for unexpected remote origins.

The project-site regression suite performs these checks against a local theme candidate. A successful test proves only the tested commit and environment; repeat it for every release candidate and after bundled dependency updates.

Content security policy

Local assets make a strict Content Security Policy practical, but OINK does not invent one universal policy for every site. Inline author HTML, ECharts callback scripts, analytics, remote specifications, and custom integrations can all change the required directives.

Start with the smallest policy that supports the site’s reviewed features. Keep ECharts options structured when callbacks are unnecessary, review inline scripts, and add remote origins only for integrations that the site deliberately enables.

1.3 - Architecture

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.

JavaScript still runs in the browser for interactive features. “Hugo-only” describes the build dependency, not a JavaScript-free user interface.

Repository boundary

Theme repository

github.com/pgsty/oink is the published Hugo Module. Its root contains the canonical layouts, partials, shortcodes, SCSS, JavaScript, fonts, icons, browser runtimes, translations, go.mod, and hugo.yaml. VENDOR.json records the bundled third-party assets.

The repository contains no project website or npm workspace. Root metadata such as README.md, LICENSE, NOTICE, theme.toml, and the vendor manifest is part of distributing and attributing the theme.

Project site repository

github.com/pgsty/oink.pgsty.com contains the documentation, bilingual examples, regression pages, site-specific layouts and assets, npm-based site tests, and deployment configuration. It imports the public theme module in hugo.yaml and pins its version in go.mod.

For local cross-repository development, an ignored go.work substitutes a sibling theme checkout. No relative filesystem replacement is committed to the site module.

Build pipeline

Hugo combines four classes of input:

1. page bundles and Markdown content from the consuming site;
2. native Hugo configuration and supported theme parameters;
3. theme templates, translations, SCSS, and JavaScript;
4. committed static or Hugo Asset resources.

Hugo compiles SCSS with its embedded pipeline, bundles page JavaScript, minifies production resources, fingerprints eligible outputs, and rewrites relative URLs for the configured baseURL. Oink does not invoke Hugo’s postCSS pipe.

The final public/ directory contains HTML, CSS, JavaScript, fonts, search indexes, feeds, sitemaps, and copied static files. It can be deployed without the source tree.

Page shell

The canonical page shell is assembled from small partials:

• a global navbar and responsive sub-navigation;
• language and color-mode controls;
• a resizable, foldable documentation sidebar;
• breadcrumbs, table of contents, reading metadata, feedback, and repository links where configured;
• a shared footer and print layouts.

Normal Hugo lookup remains available for site-specific extensions. Override the narrowest partial possible instead of copying baseof.html or the entire shell.

Conditional runtime loading

Content shortcodes record feature use in the page store. Asset partials inspect those markers and include the corresponding local runtime at most once:

flowchart TD
  S[Shortcode renders] --> M[Set page feature marker]
  M --> A[Asset assembly]
  A --> Q{Feature used?}
  Q -- Yes --> L[Bundle local runtime once]
  Q -- No --> O[Omit runtime]

This keeps a plain article free of ECharts, Asciinema, or Infographic code while allowing multiple component instances on a feature page.

Multilingual routing

Oink delegates language identity to Hugo. The selector uses each page’s .Translations and the site’s configured languages, ordered by weight. Missing translations fall back to the target-language home page. The same data drives canonical and alternate metadata.

Security boundaries

Oink keeps authored data and authored executable code explicit:

• structured ECharts options are parsed as JSON or YAML and safely serialized;
• optional ECharts JavaScript blocks register callbacks only on pages that declare them;
• component identifiers and configuration are generated by templates rather than unescaped HTML strings;
• hosted search, analytics, comments, remote media, and service endpoints remain explicit site decisions.

Goldmark’s unsafe setting permits trusted project authors to use inline HTML; it is not a sanitizer for untrusted submissions.

Upstream maintenance

Oink preserves Docsy’s source history and Apache-2.0 obligations. Upstream changes are classified as applicable, superseded by an intentional Oink difference, or unrelated. Applicable changes are ported into the canonical implementation without recreating an upstream-versus-brand runtime switch.

Extension boundary

Put an implementation in the theme when it is broadly reusable, has a stable content API, and can own its assets and accessibility behavior. Keep it in the site when it embeds product data, pricing, catalog assumptions, or a one-off landing-page structure.

1.4 - Contribution guidelines

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.

Development environment

Consumer sites need only Hugo Extended, Go, and Git. The theme repository is a direct Hugo Module. The project-site repository uses its pinned Node.js and npm versions for formatting, links, translations, and regression tests.

Install the maintainer dependencies from the repository root using the lockfile. Do not update dependencies as a side effect of an unrelated change.

The project is split across:

• github.com/pgsty/oink: published theme source and VENDOR.json;
• github.com/pgsty/oink.pgsty.com: documentation, examples, and tests.

Build the consumer contract

Always verify the path that users run from a consuming site:

hugo --gc --minify

This build must succeed without npm installation in the consumer site and without a network request for theme-owned browser assets.

For a local theme candidate, clone both repositories as siblings and activate an ignored Hugo workspace:

go work init .
go work edit -replace=github.com/pgsty/oink=../oink
HUGO_MODULE_WORKSPACE=go.work npm run build

Run focused tests

Choose the smallest relevant suite first:

npm run test:hugo-build
npm run test:alt-site
npm run test:md-output
npm run test:favicons

Run npm test for the complete site suite.

Multilingual changes should cover the one-, two-, three-, and four-or-more language states, missing-page fallback, RTL, canonical URLs, hreflang, and Open Graph locale metadata.

Content-component changes should cover single and multiple instances, no asset load on unused pages, invalid parameters, subpath builds, print, keyboard use, reduced motion, and offline behavior.

Write bilingual documentation

All user-facing pages added under content/docs/ or content/blog/ need a .zh.md peer. Follow TRANSLATION.md for terminology and Chinese typography.

Translated Markdown headings use explicit IDs copied from the English rendered HTML. Check source coverage and, after building, rendered heading IDs:

node scripts/check-doc-translations.mjs
node scripts/check-doc-translations.mjs --public public

Preserve code, configuration keys, URLs, release facts, authorship, and link definitions. Translate visible metadata, alternative text, callouts, UI labels, and shortcode strings. Do not submit placeholder or untranslated prose merely to satisfy the filename check.

Preview documentation

Run the project website with the pinned public module, or activate the local workspace described above:

npm run serve

Review English and Chinese versions of the changed pages at desktop and mobile widths. Check light and dark modes, table of contents, language switching, search, code blocks, tables, callouts, print output, and fragment links.

A local build proves only local rendering. CI, release packaging, hosted preview, and production publication are separate verification layers.

Keep changes compatible

• Reuse existing partials, shortcodes, SCSS helpers, and asset loaders.
• Load browser runtimes only on pages that use them, and at most once per page.
• Keep default behavior local-first and same-origin.
• Serialize structured data safely; arbitrary JavaScript requires an explicit unsafe boundary.
• Use logical CSS properties and test LTR and RTL.
• Preserve site-owned business components and documented compatibility aliases.
• Keep legal attribution and vendor metadata with redistributed assets.

Open the pull request

Keep commits and messages lean and explain user-visible behavior and migration impact. Include the focused commands run and their results.

If a change intentionally diverges from Docsy, update the relevant migration or release documentation. Do not remove upstream copyright, license, or history.

1.5 - Release process

Oink treats implementation, validation, publication, and deployment as different states. A green local build is useful evidence, but it is not a public tag, a downloadable module, or a deployed documentation update.

Release states

Report the exact state and evidence; do not call a local build a release.

Versioning

Theme releases use root tags such as vX.Y.Z in github.com/pgsty/oink. The theme is now the repository’s root module, so nested theme/vX.Y.Z tags are no longer used.

The project site’s version parameter identifies a published site variant and is not automatically a Git ref. Installation instructions and go.mod must use the actual resolvable theme tag.

Validate the theme repository

From a clean pgsty/oink checkout:

1. inspect the source diff and attribution changes;
2. verify every VENDOR.json file and SHA-256 entry;
3. confirm the repository has no generated public/, resource cache, node_modules/, or embedded example site;
4. build a minimal consumer through the Hugo Module path with the minimum and current supported Hugo Extended versions;
5. inspect the module zip and confirm layouts, assets, translations, static files, licenses, and notices are present.

The module zip test matters because Go excludes special directory names such as vendor from published modules. Oink stores bundled dependencies under assets/third_party/ so they survive module distribution.

Validate the project site

Clone pgsty/oink and pgsty/oink.pgsty.com as siblings, then connect them with an ignored workspace:

cd oink.pgsty.com
go work init .
go work edit -replace=github.com/pgsty/oink=../oink
export HUGO_MODULE_WORKSPACE=go.work
npm ci
npm test

Inspect representative English and Chinese pages, mobile navigation, both color modes, local search, print output, diagrams, API documentation, and 404 pages. This validates the candidate against the site; it does not publish either repository.

Tag and publish the theme

After review, create one immutable signed root tag in the theme repository:

git tag -s vX.Y.Z -m "Oink vX.Y.Z"
git push origin main vX.Y.Z

Pushing and creating a GitHub release require explicit authorization. After the tag is public, verify it from a clean environment:

hugo mod get github.com/pgsty/oink@vX.Y.Z
hugo mod graph

If an offline archive is attached to the release, publish and independently verify its SHA-256 checksum. Keep LICENSE, NOTICE, and VENDOR.json in the archive.

Update the project site

Once the theme tag resolves publicly, update the independent site repository:

hugo mod get github.com/pgsty/oink@vX.Y.Z
hugo mod tidy
npm test

Commit go.mod, go.sum, version parameters, changelog, and upgrade guidance together. Deploy previews first, then advance the production publishing branch only after review.

Post-release verification

After publication:

1. fetch the tag from a clean clone and inspect its signature;
2. resolve the module through the public Go proxy;
3. build a minimal new site with the documented commands;
4. open the production documentation and verify module instructions, canonical links, languages, search, and assets;
5. verify any released archive and checksum;
6. record the final tag, module version, hosted URLs, and artifact hashes.

Hotfix and rollback

A hotfix follows the same evidence chain with a smaller scope. Never move or replace a published tag. Roll back a site deployment to a known artifact, then publish a new patch version of the theme when necessary.

Definition of done

A release is complete only when the approved tag exists, the public module resolves, required checks pass, the project site pins the tag, and hosted smoke tests succeed. Anything less should be reported by its actual state.

1.6 - Open-source licenses and acknowledgements

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

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.

Upstream lineage

OINK is an independent theme directly derived from Docsy. It preserves Docsy’s source history, Apache-2.0 license, copyright notices, content conventions, and compatible APIs that remain part of the product. The project site is also derived from the Docsy project website and records that origin in its own NOTICE.

OINK is not an optional skin over a second Docsy installation. The inherited codebase has evolved into one standard theme with a Hugo-only consumer build, local browser runtimes, multilingual behavior, and its own release process. Contributors must retain applicable upstream notices and mark modified files as required by Apache-2.0.

Projects Oink depends on

Hugo Extended is the build platform. Go resolves the Hugo Module when a site uses the module installation path, and Git provides the source and release workflow. These tools are prerequisites; the theme does not redistribute their executables.

The theme does redistribute versioned browser assets so a consumer does not need npm or a public CDN. The following table groups the current major dependencies; VENDOR.json is authoritative for exact versions, selected artifacts, sources, checksums, and license paths.

Redistributions must keep the license and notice material required by each component. Updating a vendored file means updating its manifest entry, checksum, source, license files, and any required notice in the same change.

Projects Oink acknowledges

Fumadocs is a design reference, not Oink’s code upstream or a runtime dependency. OINK reinterprets those ideas for Hugo and its Docsy-derived codebase rather than making a pixel-for-pixel copy. We thank the Hugo, Docsy, Fumadocs, and dependency communities for publishing and maintaining their work.

These references identify lineage, dependencies, or inspiration. They do not imply endorsement, and the project and product names remain the property of their respective owners.

Reusing the documentation

CC BY 4.0 permits sharing and adaptation of covered documentation for any purpose, provided that you give appropriate credit, link to the license, and indicate whether you made changes. You must not imply that Oink, PGSTY, or an upstream project endorses the adaptation.

A concise attribution can read:

Adapted from the Oink documentation by PGSTY contributors, licensed under CC BY 4.0. Changes were made.

If a page includes separately attributed media or imported text, preserve that material’s attribution and license as well. Removing a footer does not remove the obligation to provide attribution elsewhere.

Reusing the theme

Apache-2.0 permits use, modification, and distribution of the covered theme source and compiled output, subject to its terms. In particular, preserve the license, applicable copyright and attribution notices, and the contents of NOTICE when the license requires them; mark modified files when distributing modified source.

Theme distributions should include LICENSE, NOTICE, VENDOR.json, and the third-party license files referenced by the manifest. Apache-2.0 does not grant permission to use project trademarks, and it does not turn third-party assets into Apache-licensed works.

For a source contribution or redistribution review, start with the contribution guidelines and the actual license and notice files linked below.

2 - Get Started

Oink is a Hugo theme whose complete browser runtime ships with the theme. A consumer site builds with Hugo Extended alone: no Node.js package installation, PostCSS step, CDN, or build-time remote asset download is part of the default path.

Choose a starting point

• Hugo Module — recommended: import github.com/pgsty/oink in an existing or new Hugo site. See the Oink quick start.
• Project site: use the independent pgsty/oink.pgsty.com repository as a complete bilingual configuration and regression reference.
• Existing Docsy site: follow the migration guide to remove common overrides and the consumer npm asset pipeline without rewriting content.

Install the prerequisites

Install Git, Go, and Hugo Extended 0.160.1 or newer. See Before you begin for platform notes and verification commands.

Add Oink

From the site root:

hugo mod init github.com/example/product-docs
hugo mod get github.com/pgsty/oink@THEME_REF

Then import the theme in hugo.yaml:

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

Pin THEME_REF to a released tag or immutable commit and commit go.mod and go.sum.

Build contract

The same commands preview and build every supported module consumer:

hugo server --disableFastRender
hugo --gc --minify

Next steps

1. Set the basic configuration.
2. Add repository, copyright, logo, and menu values.
3. Put translations side by side as page.md and page.zh.md.
4. Add and customize content.
5. Choose a deployment target.

2.1 - Before you begin

The consumer prerequisite is Hugo Extended. Git and Go are conditional on how the theme source is obtained.

Install Hugo Extended

Install version 0.160.1 or newer. The current validation baseline is 0.164.0. A release’s support matrix takes precedence when these values change.

Verify the selected binary:

hugo version

The output must contain extended. Standard Hugo cannot compile the theme’s SCSS. Use Hugo’s official installation guides for the platform and pin the same version in local development and CI.

Install Git when needed

Git is required to clone the site, use submodules, preserve .GitInfo, or fetch a theme checkout. Verify it with:

git --version

A site built from an already extracted offline archive can run Hugo without network access, but keeping the source in version control remains recommended.

Install Go only for Hugo Modules

Hugo’s module commands use Go. Install Go when the site imports the theme as a Hugo Module, then verify:

go version
hugo mod graph

A versioned archive, adjacent theme directory, or Git submodule does not require Go at site build time.

Do not install a frontend toolchain

OINK ships Bootstrap, Font Awesome, LTR and RTL CSS, fonts, search, and browser runtimes as local versioned assets. Consumer sites do not install Node.js, npm, PostCSS, Autoprefixer, or RTLCSS for the theme.

Node-based commands in the project-site repository are maintainer-only tools. The production consumer command is:

hugo --gc --minify

Check the complete distribution

For offline or air-gapped use, confirm that the theme archive contains go.mod, hugo.yaml, assets/, layouts/, static/, i18n/, LICENSE, NOTICE, and VENDOR.json. Install Hugo Extended before entering the isolated environment, then run the same build command with network access disabled.

What’s next?

• Inspect the bilingual project site
• Create a site from scratch
• Compare distribution options

2.2 - Install Oink

Oink is published as the Hugo Module github.com/pgsty/oink. A consuming site builds with Hugo Extended alone; Node.js, npm, PostCSS, and CDN-hosted browser packages are not part of the build contract.

Prerequisites

Install Git, Go, and Hugo Extended 0.160.1 or newer. The project site currently validates with 0.164.0:

git --version
go version
hugo version

The Hugo version output must include extended.

Add the module

From your Hugo site root, initialize a module if the site does not already have one, then pin an Oink release:

hugo mod init github.com/example/product-docs
hugo mod get github.com/pgsty/oink@THEME_REF

Replace THEME_REF with a published tag such as v0.2.0 or an immutable commit. Add the import to hugo.yaml:

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

Commit the resulting go.mod and go.sum. Do not run production builds against an unpinned branch.

Preview the site

Start an editing server:

hugo server --disableFastRender

Create a production artifact with:

hugo --gc --minify

Oink ships Bootstrap, Font Awesome, fonts, search, diagrams, API documentation runtimes, and its content components. A consuming site does not need a node_modules directory.

Develop against a local checkout

Clone the theme and site as siblings, then use a local Go workspace:

~/pgsty/
├── oink/
└── product-docs/

cd ~/pgsty/product-docs
go work init .
go work edit -replace=github.com/pgsty/oink=../oink
export HUGO_MODULE_WORKSPACE=go.work
hugo server

Keep go.work out of version control. The committed go.mod remains pinned to the public module; the workspace substitutes the sibling checkout only on your machine.

Add bilingual content

Create the English page first:

content/docs/operations.md

Then add its translation beside it:

content/docs/operations.zh.md

Keep front matter identifiers, code, commands, parameter names, and link targets semantically aligned. Translate reader-facing prose. For stable cross-language deep links, preserve the English heading ID explicitly in the Chinese heading:

## 故障恢复 {#failure-recovery}

Configure the minimum site

The essential configuration is small:

title: Product Docs
baseURL: https://docs.example.com/
defaultContentLanguage: en

languages:
  en:
    label: English
    locale: en-US
    weight: 1
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2

params:
  logo: icons/logo.svg
  offlineSearch: true

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.160.1

Add menus, outputs, markup extensions, repository links, and optional features as the site grows. See Configuration for the supported model.

Validate before publishing

At minimum:

1. build from a clean checkout with the committed module files;
2. run hugo --gc --minify with the pinned Hugo Extended version;
3. browse representative English and Chinese pages;
4. verify language switching, search, mobile navigation, dark mode, and print;
5. inspect browser network requests if the site promises offline operation.

These checks establish a build artifact. Publishing that artifact and verifying the hosted URL are separate deployment steps.

2.3 - Create a new site

The independent bilingual project site is a useful reference. Use this procedure to create a smaller site with its own content structure.

Create the site skeleton

Run:

hugo new site --format yaml my-new-site
cd my-new-site

Initialize the site module and pin Oink:

hugo mod init github.com/example/my-new-site
hugo mod get github.com/pgsty/oink@THEME_REF

Add minimum configuration

Use this as hugo.yaml:

title: Product Docs
baseURL: https://docs.example.com/
defaultContentLanguage: en

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    menus:
      main:
        - { name: Docs, pageRef: /docs, weight: 10 }
        - { name: Blog, pageRef: /blog, weight: 20 }
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    menus:
      main:
        - { name: 文档, pageRef: /docs, weight: 10 }
        - { name: 博客, pageRef: /blog, weight: 20 }

markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:
    noClasses: false

params:
  offlineSearch: true
  ui:
    showLightDarkModeMenu: true
    sidebar_menu_foldable: true

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.160.1

Commit go.mod and go.sum. Do not add npm mounts or a PostCSS pipeline.

Add bilingual content

Create these files:

content/
├── _index.md
├── _index.zh.md
├── docs/
│   ├── _index.md
│   ├── _index.zh.md
│   ├── getting-started.md
│   └── getting-started.zh.md
└── blog/
    ├── _index.md
    └── _index.zh.md

Every page needs front matter. For example, content/docs/getting-started.md:

---
title: Getting started
weight: 10
---

## Install {#install}

Install the product.

Its getting-started.zh.md translation keeps the explicit heading ID:

---
title: 开始使用
weight: 10
---

## 安装 {#install}

安装产品。

Using the same explicit ID in both examples is harmless and makes the intended cross-language contract visible. In a translated existing page, copy the ID from the English rendered HTML.

Preview and build

Run the development server:

hugo server --disableFastRender

Then verify the production build separately:

hugo --gc --minify

Check /docs/, /zh/docs/, the language selector, local search indexes, and the browser console before adding custom layouts.

Add features incrementally

Copy logo and brand assets first, then add repository links and menus. Add diagrams, API documentation, and content components only on pages that need them; OINK will publish their local runtimes on demand.

If a site needs a business-specific shortcode, keep it under the site’s own layouts/_shortcodes/. Move it into the theme only after its interface is free of site assumptions and multiple sites can reuse it.

What’s next?

• Expand the basic configuration.
• Learn how to add content.
• Review the OINK architecture.
• Select a deployment target.

2.4 - Basic site configuration

Hugo reads site-wide settings from hugo.yaml, hugo.toml, or hugo.json. The The Oink project site uses YAML because multilingual menus and theme options remain easy to scan and review.

Minimum configuration

The following excerpt shows the important structure for the Hugo Module.

 1title: Product Documentation
 2baseURL: https://docs.example.com/
 3defaultContentLanguage: en
 4
 5languages:
 6  en:
 7    label: English
 8    locale: en-US
 9    weight: 1
10    title: Product Documentation
11    menus:
12      main:
13        - name: Docs
14          pageRef: /docs
15          weight: 10
16        - name: Blog
17          pageRef: /blog
18          weight: 20
19  zh:
20    label: 简体中文
21    locale: zh-CN
22    weight: 2
23    title: 产品文档
24    menus:
25      main:
26        - name: 文档
27          pageRef: /docs
28          weight: 10
29        - name: 博客
30          pageRef: /blog
31          weight: 20
32
33markup:
34  goldmark:
35    renderer:
36      unsafe: true
37  highlight:
38    noClasses: false
39
40params:
41  offlineSearch: true
42  github_repo: https://github.com/example/product-docs
43  github_branch: main
44  copyright:
45    authors: Example Authors
46    from_year: 2026
47  ui:
48    showLightDarkModeMenu: true
49    sidebar_menu_foldable: true
50    breadcrumb_disable: false
51
52module:
53  imports:
54    - path: github.com/pgsty/oink
55  hugoVersion:
56    extended: true
57    min: 0.160.1

English has weight 1 and is the default language; Simplified Chinese has weight 2; additional languages follow. The language selector uses this order when a click cycles to the next language and when the full hover menu is rendered.

Content translations

Put translations beside each other:

content/
├── _index.md
├── _index.zh.md
├── docs/
│   ├── _index.md
│   ├── _index.zh.md
│   ├── install.md
│   └── install.zh.md
└── blog/
    ├── release.md
    └── release.zh.md

Keep route-affecting metadata aligned. Translate titles, descriptions, menu labels, summaries, tags, image alternatives, and visible shortcode strings. Use the English rendered heading ID as an explicit ID on each translated heading so that fragments remain stable across languages.

Local search and browser resources

offlineSearch: true enables the theme’s same-origin Lunr index and CJK fallback. The index is generated per language. Do not configure a public search service unless the site intentionally accepts that network dependency.

Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, and Infographic are provided locally and loaded per page. PlantUML and Draw.io are service-based exceptions: configure an approved endpoint explicitly or keep them disabled.

Branding and repository links

Set title, per-language titles, params.logo, repository URLs, copyright, and menus at the site layer. OINK does not add an oink.* configuration tree; it uses Hugo and compatible Docsy parameter locations.

Repository metadata enables edit, view, issue, and age information on content pages. Keep github_repo, github_project_repo, github_branch, and github_subdir consistent with the source layout.

Production defaults

• Use a real production baseURL, including any subpath.
• Keep online analytics, comments, Google CSE, Algolia, and remote embeds off unless they are an explicit product choice.
• Pin Hugo Extended and the theme release in CI.
• Run hugo --gc --minify as the production command.
• Keep LICENSE, NOTICE, and the vendor manifest in redistributed archives.

See the project site’s complete hugo.yaml for a buildable reference.

2.5 - Inspect the bilingual project site

The independent pgsty/oink.pgsty.com repository is the complete bilingual example and regression site. It is intentionally more comprehensive than a minimal consumer: use it as a reference, then keep only the content and configuration your product needs.

Clone the project site

Clone the project site and build its pinned public Oink release directly:

git clone https://github.com/pgsty/oink.pgsty.com.git product-docs
cd product-docs
hugo --gc --minify

The committed go.mod pins github.com/pgsty/oink. For local theme development, clone the theme as a sibling and use the workspace commands documented in the Oink quick start.

Run the site checks

Building or previewing a site with Oink does not require Node.js or installing npm packages. Node.js and the development dependencies in this example repository are needed only when maintaining the project site and running its formatting, link, translation, and regression checks:

npm ci
npm test

Open the generated site and check both English and Chinese pages. Use the language switcher from a translated detail page, not only from the home page.

Replace the example identity

Edit hugo.yaml and the files under config/, then replace:

• site and per-language titles and descriptions;
• baseURL;
• repository and branch URLs;
• copyright holder and starting year;
• logo and brand assets;
• English and Chinese menu labels.

Do not create an oink.* parameter namespace. Use Hugo’s language, menu, module, output, and markup settings plus the documented theme parameters.

Replace the example content

Keep each translation pair together:

content/docs/getting-started.md
content/docs/getting-started.zh.md

Delete historical and regression content that the product does not need. Remove an example asset only after no page references it.

For translated headings, use the English rendered ID explicitly:

## Configure search

## 配置搜索 {#configure-search}

Put the new site in version control

Change the module path, repository metadata, and remote before publishing a derived site. Keep the Oink version pinned in go.mod. Do not commit generated public/ output unless the hosting workflow explicitly requires it.

What’s next?

• Review basic configuration.
• Learn the content components.
• Configure deployment.
• Use the release checklist.

2.6 - Run OINK in a container

A container is optional: OINK itself only needs Hugo Extended. Use a container when the team wants a pinned tool image or does not install Hugo on developer workstations.

Create the Hugo image

The following Dockerfile installs the currently validated Hugo Extended version from its release package. Keep the version aligned with the theme’s support matrix.

FROM debian:bookworm-slim

ARG HUGO_VERSION=0.164.0
ARG TARGETARCH

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl git \
    && curl -L -o /tmp/hugo.deb \
      "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.deb" \
    && apt-get install -y /tmp/hugo.deb \
    && rm -rf /var/lib/apt/lists/* /tmp/hugo.deb

WORKDIR /src
EXPOSE 1313
ENTRYPOINT ["hugo"]
CMD ["server", "--bind", "0.0.0.0", "--disableFastRender"]

Build it from the site root:

docker build -t oink-hugo .

The image build downloads Hugo. For an air-gapped environment, mirror the base image and Hugo package in advance or use OINK’s complete offline distribution with an approved internal image.

Preview the site

Mount the complete site source, including its adjacent or vendored theme:

docker run --rm -it \
  -p 1313:1313 \
  -v "$PWD:/src" \
  oink-hugo

Open http://localhost:1313/. Changes on the host are visible to Hugo’s live reload process inside the container.

Run a production build

Override the default server command:

docker run --rm \
  -v "$PWD:/src" \
  oink-hugo --gc --minify

The generated site is written to public/ in the mounted source directory. Ensure the container user can write there; in a shared environment, run with a mapped user ID or fix ownership according to local policy.

No Node.js, npm, PostCSS, or remote browser asset step belongs in this image.

2.7 - Other setup options

The recommended installation uses the github.com/pgsty/oink Hugo Module. The following options change how Hugo obtains the same theme source; they do not change content or the Hugo-only build command.

Prerequisites

Every option requires Hugo Extended 0.160.1 or newer. Git options require Git, and Hugo Modules require Go. None of the options requires Node.js, npm, PostCSS, or Autoprefixer for the consuming site.

Option 1: complete release archive

The complete offline archive contains the theme, local browser runtimes, fonts, licenses, notices, vendor manifest, and checksums. It is the preferred input for air-gapped builds and the simplest way to preserve an exact distribution.

Extract the theme under the site’s themes/ directory:

site/
├── hugo.yaml
└── themes/
    └── oink/

Configure:

theme: oink

Verify the archive checksum before extracting it. Use only an archive attached to an explicit release, not a locally assembled file presented as a published distribution.

Option 2: Git submodule

A submodule records the exact OINK repository commit in the site repository:

git submodule add https://github.com/pgsty/oink.git themes/oink
git -C themes/oink fetch --tags
git -C themes/oink checkout THEME_REF
git add .gitmodules themes/oink
git commit -m "Add OINK theme at THEME_REF"

Configure the nested theme path:

theme: oink

CI must initialize submodules before running Hugo. Pin THEME_REF to a release tag or immutable commit; do not leave production on main.

Option 3: pinned Git clone

A clone works when the hosting platform requires the complete theme tree in the build input or when the site vendors a reviewed copy:

git clone https://github.com/pgsty/oink.git themes/oink
git -C themes/oink checkout THEME_REF

Use the same theme: oink setting. Record the resolved commit and the process that restores the clone. If the files are committed into the site repository, preserve OINK’s LICENSE, NOTICE, and VENDOR.json.

OINK is not distributed as an npm package. Existing Docsy npm consumers should follow the npm migration guide.

Option 4: Hugo Module

Pin the public module to a release tag or immutable commit:

hugo mod get github.com/pgsty/oink@THEME_REF
hugo mod tidy

Import it in hugo.yaml:

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

For local theme development, use an ignored Go workspace that includes the site module and a sibling OINK checkout.

Preview and verify

All source options use the same commands:

hugo server --disableFastRender
hugo --gc --minify

Verify that a clean production build succeeds with no node_modules directory, that local assets resolve under the configured baseURL, and that both English and Chinese pages and search indexes are present.

See Upgrade Oink for version changes and override review.

2.8 - Troubleshooting and known issues

Start diagnosis from a clean production build:

hugo --gc --minify --logLevel info

The consumer command should not invoke npm, PostCSS, Autoprefixer, or download theme browser assets.

Build issues

Hugo is not Extended or is too old

Run hugo version. The output must include extended, and the version must be at least 0.160.1. If a shell, editor, CI runner, or container still selects an older binary, inspect its PATH and pinned tool configuration rather than installing another copy blindly.

The theme cannot be found

An error such as module "github.com/pgsty/oink" not found means that Hugo cannot resolve the configured theme. Check the selected installation mode:

• for a Git checkout, the theme name and directory path must agree;
• for a Hugo module, run hugo mod graph and inspect go.mod, go.sum, and any configured Hugo workspace or replacement;
• for a CI checkout, initialize the pinned submodule or restore the complete release archive before running Hugo.

A local browser asset is missing

Do not fix a missing Bootstrap, Font Awesome, Lunr, Mermaid, or other OINK asset by adding a CDN URL. Confirm that the distribution is complete and contains assets/third_party/, assets/js/third_party/, static/webfonts/, and VENDOR.json. Re-extract or re-fetch the same pinned release if files are missing.

Language and link issues

A translated page does not appear

Check all four conditions:

1. languages.zh exists and has a weight in hugo.yaml.
2. The file is named page.zh.md, including lowercase zh.
3. The translated front matter does not set draft: true or a future date.
4. Route-affecting metadata matches the source unless a different route is intentional.

The language selector links to a page translation when Hugo reports one; otherwise it deliberately falls back to the target-language home page.

A fragment link opens the page but not the heading

Translated heading text normally generates a different automatic ID. Add the English rendered ID explicitly to the translated heading:

## 安装 {#installation}

Do not infer IDs for headings containing shortcodes or inline HTML. Inspect the English rendered HTML, then compare the English and Chinese heading ID lists.

Search issues

With offlineSearch: true, each language produces its own search index. Check that offline-search-index.en.json and offline-search-index.zh.json exist in the output and that the browser requests them from the site’s base URL. A wrong baseURL is a common cause of missing indexes on subpath deployments.

Chinese tokenization uses the theme’s CJK fallback. If results are empty, first verify that the Chinese page content is present in the Chinese index rather than changing the tokenizer.

Platform issues

macOS reports too many open files

Large live-preview trees can exceed the shell’s open-file limit. Inspect the current limit with ulimit -n and raise it temporarily for the current shell if local policy permits. Prefer excluding generated or unrelated directories from the watched tree before applying a machine-wide limit change.

Windows Subsystem for Linux is slow or misses changes

Run Hugo against a Linux filesystem path rather than a Windows-mounted path. Cross-filesystem notification and permission behavior can make live reload slow or unreliable.

Diagnostic checklist

• Reproduce with the exact pinned Hugo Extended version.
• Remove stale public/ and resources/ output through the project’s normal clean command, then rebuild.
• Compare development and production configuration layers.
• Check the first build error, not only the final cascading message.
• Test a minimal page to separate theme behavior from site overrides.
• Re-enable site overrides and content components in small groups.
• Inspect the browser console and network log for the failing page.

3 - Authoring

Start with site-wide configuration, then shape the content tree, writing conventions, navigation, visual language, media, shortcodes, and reusable components. These pages focus on authoring choices that remain under the consuming site’s control.

3.1 - Configuration

OINK follows a “native first” configuration model. Site identity, languages, menus, outputs, taxonomies, markup, and modules stay in their Hugo-defined locations. Existing Docsy parameters remain where their semantics are useful. OINK adds only focused choices for behavior that cannot be inferred.

Configuration rules

1. Prefer Hugo configuration over a theme-specific duplicate.
2. Prefer an established Docsy parameter over an OINK synonym.
3. Put brand, content, repository, and UI choices in their semantic locations.
4. Keep internal vendor paths and template composition out of the public API.
5. Fail early for invalid values or a missing required endpoint.

There is no oink.enabled flag and no params.oink.* tree. Adding either would create a second theme mode and make every fix, test, and document ambiguous.

A complete baseline

This example makes English primary and Simplified Chinese secondary:

title: Product Documentation
baseURL: https://docs.example.com/
defaultContentLanguage: en
enableRobotsTXT: true

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    title: Product Documentation
    menus:
      main:
        - { name: Docs, pageRef: /docs, weight: 10 }
        - { name: Blog, pageRef: /blog, weight: 20 }
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    title: 产品文档
    menus:
      main:
        - { name: 文档, pageRef: /docs, weight: 10 }
        - { name: 博客, pageRef: /blog, weight: 20 }

outputs:
  home: [HTML]
  section: [HTML, RSS, print]

markup:
  goldmark:
    renderer:
      unsafe: true
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]
  highlight:
    noClasses: false

params:
  logo: icons/logo.svg
  offlineSearch: true
  offlineSearchIndex: summary
  offlineSearchMaxResults: 10
  github_repo: https://github.com/example/product-docs
  github_branch: main
  footer_icp: ''
  footer_icp_url: https://beian.miit.gov.cn/
  copyright:
    authors: Example Authors
    from_year: 2026
  ui:
    showLightDarkModeMenu: true
    quick_links: [docs, blog]
    sidebar_menu_foldable: true
    sidebar_item_overflow: wrap
    breadcrumb_disable: false

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.160.1

The module version is pinned in the site’s go.mod. A conventional theme checkout can instead use theme: oink with the repository under themes/oink/.

Languages

defaultContentLanguage determines the unprefixed primary site. Language weight controls the visible order. label is the language’s self-name, and locale supplies the full HTML and SEO locale. Add languageDirection: rtl to an RTL language.

File naming

For the colocated model used by this site:

content/docs/guide.md
content/docs/guide.zh.md

Files with the same base name are translations. Keep their logical page identity aligned. OINK reads Hugo’s translation relationships; it does not guess from arbitrary URL patterns.

Selector states

The selector needs no mode parameter. It is hidden for one configured language. With two or more, clicking the language icon advances to the next language by weight; hovering for half a second or focusing it opens the complete menu.

If the current page lacks a target translation, the target-language home page is used. Do not add dead page-shaped URLs merely to keep the selector on the same path.

Brand and repository

Set the site and per-language title and description. params.logo can point to a Hugo Asset or a path under static/. Keep favicons and social images in the documented asset locations.

Repository metadata drives “edit this page,” issue, and last-modified links:

params:
  github_repo: https://github.com/example/product-docs
  github_project_repo: https://github.com/example/product
  github_branch: main
  github_subdir: site

github_project_repo defaults to github_repo where supported. github_subdir is the content site’s path inside a monorepo. Keep github_branch resolvable; a display version is not necessarily a Git ref.

Use params.wordmark for a horizontal brand asset that should appear in the landing navigation, documentation header, mobile drawer, and footer. It accepts the same asset and static/ paths as params.logo. If wordmark is absent, OINK keeps the existing logo-and-title treatment:

params:
  logo: images/product-mark.svg
  wordmark: images/product-wordmark.svg

Navigation and layout

OINK retains Docsy menus and UI parameters and adds focused shell controls:

params:
  page_width: normal
  ui:
    quick_links: [docs, blog]
    sidebar_width_min: 220
    sidebar_width_max: 480
    sidebar_item_overflow: wrap
    sidebar_menu_compact: true
    sidebar_menu_foldable: true
    sidebar_root_enabled: true
    sidebar_root_menu: true
    sidebar_search_disable: false
    breadcrumb_disable: false
    showLightDarkModeMenu: true
    page_context_menu:
      enable: true
      links: []
    readingtime:
      enable: true

page_width accepts normal, wide, or full and can be overridden in page front matter. Sidebar minimum and maximum values are pixels used to clamp the desktop drag resizer. sidebar_item_overflow: wrap wraps long labels; other values retain the compact ellipsis behavior.

quick_links names top-level page references shown by the shell. Define their translated names in each language’s main menu.

The page context menu keeps Open in ChatGPT / Claude, Copy as Markdown, View Markdown, edit, issue, and print actions reachable at every viewport width. The built-in assistant links appear on documentation pages and send the current URL inside a localized prompt only when a reader activates one; they do not upload the page body. links is empty by default. Additional custom links accept URL-encoded {url}, {title}, and {markdown_url} placeholders:

params:
  ui:
    page_context_menu:
      enable: true
      links: []
      # - name: Ask an external assistant
      #   icon: fa-solid fa-wand-magic-sparkles
      #   url: https://assistant.example/new?source={markdown_url}&title={title}

Homepage and footer

Homepage content lives in data/home/<language>.yaml, with English used as the fallback. Each language file contains named data blocks and an optional sections list that composes those blocks into the exact landing-page order. The footer uses the same file but is rendered independently of sections.

Compose sections

A string entry uses the same value as its section type and data key. A map entry can select a built-in type, read a differently named key, set a stable id, or temporarily set enabled: false:

sections:
  - hero
  - metrics
  - capabilities
  - type: logo_wall
    key: ecosystem
  - gallery
  - faq
  - cta

ecosystem:
  title: Built with familiar tools
  columns: 4
  items:
    - {
        name: Hugo,
        icon: fa-solid fa-bolt,
        url: https://gohugo.io/,
        external: true,
      }

Map entries may also carry their content in data, which is useful for a short one-off block. Reuse a built-in type with different keys when two sections need the same presentation. A site-owned layout can name an explicit partial, but that is a custom template contract rather than portable homepage data.

If sections is absent, OINK preserves the 0.1.x order by rendering the blocks that exist among hero, metrics, capabilities, principles, and cta. Adding sections opts into explicit composition; omitted blocks then stay out of the page even if their data remains in the file.

Built-in sections

OINK 0.2.0 provides 12 section types:

Common collection blocks accept eyebrow, title, desc or text, columns, and items. Item fields vary by presentation but consistently use title or name, desc or text, icon, image, url, and external. Ordinary text fields render Markdown. Keep internal URLs relative to the language root; set external: true for links that should open as external navigation.

Hero media and brand footer

Every block is optional, so a site can keep a short landing page without copying the layout. For example:

hero:
  eyebrow: Local-first documentation
  title_lines:
    - words:
        - { mark: P, text: roduct, color: red }
        - { mark: D, text: ocs, color: blue }
  lead: Documentation built and served with Hugo.
  image:
    light: images/hero-light.webp
    dark: images/hero-dark.webp
    alt: Product documentation workflow
  actions:
    - {
        label: Read the docs,
        url: docs/,
        icon: fa-solid fa-book,
        style: primary,
      }

footer:
  brand:
    name: Product Docs
    tagline: A short **Markdown-enabled** description.
    slogan: Clear answers, close to the product.
  columns:
    - title: Product
      links:
        - { label: Overview, url: docs/ }

The optional hero.image block adds a theme-aware visual on the right. Set light and dark to files under the site’s static/ directory; the active image follows the color-theme selector. If only src, light, or dark is provided, OINK uses that image for both themes. A string value is also accepted as a shared image. Omit image to keep the text-only Hero.

The homepage renders the large brand-and-navigation footer above the common footline. The footline uses params.copyright on the left, optional params.footer_icp and params.footer_icp_url in the center, and every configured language on the right. Markdown in the copyright author and footer brand text is rendered as links and inline markup.

Linked capability boards

A capability row can turn its component board into a compact navigator. Add a url to each linked item, name the region with aria_label, and choose one to four columns. Items without a URL remain decorative, so existing boards keep their current behavior:

capabilities:
  items:
    - title: Content on demand
      visual:
        type: components
        aria_label: Browse content components
        columns: 3
        compact: true
        items:
          - {
              title: Asciinema,
              icon: fa-solid fa-terminal,
              url: docs/content/components/#asciinema,
            }
          - {
              title: Mermaid,
              icon: fa-solid fa-share-nodes,
              url: docs/content/diagrams-and-formulae/#diagrams-with-mermaid,
            }

Search

The project site enables local search by default:

params:
  offlineSearch: true
  offlineSearchIndex: summary
  offlineSearchSummaryLength: 70
  offlineSearchMaxResults: 10

offlineSearchIndex controls how much text is downloadable in each language’s index. The scopes are cumulative: title indexes titles and taxonomy metadata; heading adds page headings; summary adds descriptions or summaries; and content also adds the complete body. content is the compatibility default, while summary is a smaller starting point for most documentation sites. offlineSearchMaxResults applies to both Lunr and the CJK substring fallback.

Each language receives a distinct index. Hosted alternatives remain supported through their established Docsy settings, but enabling them intentionally adds an external service boundary. Do not configure several competing search providers without also deciding which UI should be visible.

Content runtimes

Browser-only runtimes

Mermaid and KaTeX are detected from content. Enable Markmap at the site level:

params:
  markmap:
    enable: true
  mermaid:
    theme: default

Swagger UI, Redoc, Asciinema, ECharts, Infographic, and carousel assets load when their shortcodes appear. Their local runtime paths are internal and should not be configured.

Service endpoints

PlantUML and Diagrams.net require explicit endpoints:

params:
  plantuml:
    enable: true
    svg: true
    svg_image_url: https://diagrams.internal.example/plantuml/svg/
  drawio:
    enable: true
    drawio_server: https://diagrams.internal.example/

Leave the features disabled in an air-gap site unless those URLs are reachable inside the isolated network.

Page-level overrides

Hugo’s .Param lookup allows many site parameters to be overridden in front matter:

---
title: Wide reference
page_width: wide
hide_feedback: true
hide_readingtime: true
ui:
  no_left_sidebar: false
  scrollSpy:
    disable: false
---

Use overrides for real content differences, not to reconstruct a separate visual system page by page.

Avoid false configuration

Do not expose:

• a switch between “Docsy” and “OINK” shells;
• paths to vendored JavaScript, CSS, fonts, or internal partials;
• duplicated language or repository values under a brand namespace;
• toggles that merely select one of two copied implementations.

If a site needs a custom product matrix or portal, keep that component in the site and use a narrow hook or shortcode. A local business feature is clearer than a misleading global theme option.

Validate changes

After changing configuration:

1. build with the minimum supported Hugo Extended version and the current validation version;
2. test every configured language and one page without a translation;
3. verify root and subpath baseURL output if both are supported;
4. inspect local search and optional runtime requests;
5. check the desktop and mobile shell, dark and light themes, and print output.

An accepted configuration is one that builds and behaves correctly, not merely one that parses as YAML.

3.2 - Adding content

OINK uses Hugo’s content model: Markdown carries the information, front matter carries page metadata, and layouts turn both into a static site. This guide describes the conventions used by the bundled English and Simplified Chinese sample site.

Content root directory

Site content lives below content/. A multilingual site can use separate roots such as content/en/ and content/zh/, or translated filename suffixes in one mounted tree. This repository uses the second form:

content/docs/content/
├── adding-content.md
└── adding-content.zh.md

The English file is the source page and the .zh.md file is its Simplified Chinese translation. Both files share the same logical path after Hugo applies the language suffix.

Keep generated files and files that must be copied byte-for-byte outside the content tree. Put those in static/ as described in Adding static content.

Content sections and templates

Every top-level content directory is a Hugo section. OINK includes layouts for:

• docs: documentation with a section tree, table of contents, breadcrumbs, previous/next navigation, and repository links;
• blog: dated articles, taxonomy metadata, feeds, and chronological lists;
• community: project and contributor links;
• default pages: landing pages without the documentation sidebar.

Hugo chooses a layout from the content section. A page below content/docs/ therefore uses the docs layout. Set type in front matter only when a page must use another section’s layout.

Custom sections

Create a directory below the content root, then give its pages a type when the default layout is not sufficient:

---
title: Architecture decisions
description: Accepted design decisions for the project.
type: docs
weight: 30
---

For section-wide behavior, put shared values in the section’s _index.md cascade rather than repeating them on every page. Add a project layout under layouts/ only when no existing OINK layout or partial is suitable.

Doc-rooted sites

EXPERIMENTAL

A documentation-first site can publish the docs section at the URL root while keeping source files under content/.../docs/:

permalinks:
  page:
    docs: /:sections[1:]/:slug/
  section:
    docs: /:sections[1:]

The docs section landing page then becomes the home page. Add this front matter to the physical site-root index for each language so it can still act as a link without competing for the same output path:

build: { render: link }

Check for path conflicts

Docs now share the URL root with blog, community, and other sections. Build with --printPathWarnings and resolve every duplicate target before publishing:

hugo --printPathWarnings

Legacy docs-only setup

Older Docsy examples used a front matter cascade to force page types. Remove that workaround when moving to the permalink-based doc-rooted setup; otherwise the home page and section layouts can resolve inconsistently.

Page front matter

Front matter is page metadata written in YAML, TOML, or JSON. OINK’s sample site uses YAML:

---
title: Local-first architecture
linkTitle: Local-first
description: How OINK removes browser and build-time CDN dependencies.
weight: 20
date: 2026-08-08
tags: [architecture, offline]
---

title is the practical minimum. In maintained documentation, also provide a concise description for search and metadata, and a weight when order matters. Use linkTitle only when navigation needs a shorter label.

Translations should localize human-facing metadata while preserving structural values:

---
title: 本地优先架构
linkTitle: 本地优先
description: OINK 如何消除浏览器端与构建期的 CDN 依赖。
weight: 20
date: 2026-08-08
tags: [架构, 离线]
---

Do not translate keys, shortcode names, configuration keys, file paths, or stable identifiers.

Footer metadata

Docs and blog pages render a compact metadata block above the site footer. The last-modified date comes from Hugo’s .Lastmod value. Two optional front matter fields add provenance notices:

lastmod: 2026-08-09
upstream_attribution: https://upstream.example/docs/page/
downstream_modified: true

upstream_attribution links to the upstream source and its attribution. downstream_modified: true states that the downstream project changed the page. Omit either field when its notice does not apply.

Page content

Write pages in Markdown unless a layout genuinely requires HTML. Hugo renders Markdown with Goldmark and supports attributes, footnotes, tables, task lists, render hooks, and fenced code blocks.

Markdown

Keep source readable without the rendered site:

• use ATX headings (## Heading);
• put blank lines around lists, blocks, and fenced code;
• specify the language of every code fence when one exists;
• use descriptive link text and image alternative text;
• wrap prose at a review-friendly width, but never reflow code or URLs.

OINK adds render hooks for blockquote alerts and for Mermaid, math, chemistry, Markmap, and PlantUML code blocks. See Diagrams and Formulae.

Markup, shortcodes, and content features

Use standard Markdown for ordinary prose. Use a shortcode when it supplies meaningful behavior such as tabs, cards, a terminal recording, an API viewer, or a safe chart. Shortcodes are part of the content contract: verify their arguments in both languages and avoid copying rendered HTML into translations.

Alerts

OINK supports GitHub-style blockquote alerts and optional Obsidian-style titles:

> [!TIP]
>
> Run the translation audit before every release.

> [!WARNING] Stable anchors required
>
> A translated heading must keep the English page's rendered ID.

Supported semantic types include NOTE, TIP, IMPORTANT, WARNING, and CAUTION, plus the Bootstrap-compatible types and NB. Use alerts sparingly: important instructions must still make sense to screen readers and in print. See Alerts for appearance.

Links

Use root-relative links for stable public routes and ordinary relative links for nearby pages or bundle resources. Hugo’s ref and relref shortcodes validate content references and account for language and permalink rules:

[Configuration]({{< ref "/docs/about/configuration" >}})

For bilingual pages:

• link to the logical page, not directly to a .zh.md filename;
• keep fragment IDs language-neutral;
• verify that both language variants resolve the same fragment;
• use relref when the destination must remain relative to the current host.

Run the internal-link check after changing routes or headings.

Content style

Write task-oriented documentation in direct language. Introduce a concept before its configuration, state defaults explicitly, and distinguish local build verification from deployment or publication. The Chinese edition follows the terminology and typography rules in oink.pgsty.com/TRANSLATION.md.

Page bundles

A standalone page is a single Markdown file. A leaf bundle is a directory with an index.md and page resources:

content/docs/tutorial/
├── index.md
├── index.zh.md
├── architecture.svg
└── example.yaml

Both language pages can use the same image and downloadable file. Hugo normally shares page resources across language variants on a single host, so do not duplicate identical binary assets. Localize an image only when it contains meaningful text; give the localized resource a clear language suffix.

Use branch bundles (_index.md) for sections that contain child pages and leaf bundles (index.md) for terminal pages with resources.

Adding docs, blog posts, and release notes

Create every maintained English page and its Chinese peer in the same directory:

guide.md
guide.zh.md

For bundle pages, pair index.md with index.zh.md. Keep routing metadata, dates, weights, aliases, and resource declarations aligned unless a language-specific difference is intentional.

Organizing your documentation

Use directories to reflect the reader’s information architecture, not the implementation’s package tree. Each documentation subsection needs an _index.md and an _index.zh.md. Child pages appear in the sidebar ordered by weight, then by the configured fallback ordering.

Prefer a shallow hierarchy. Split a page when it serves a distinct task or audience; do not split merely to shorten a file. See Organizing Your Content.

Docs section landing pages

A docs _index.md renders child-page summaries by default. Use:

simple_list: true

to render a compact list, or:

no_list: true

to suppress the generated list. Give each language variant a localized title and description, and keep the structural option identical.

Organizing blog posts and release notes

Separate posts by publisher and audience. Keep every upstream Docsy article, including Docsy release reports, flat under blog/docsy/. Keep OINK-specific articles flat under blog/oink/, and reserve blog/release/ for versioned OINK release notes. Do not add year subdirectories; pair each article in place:

content/blog/
├── docsy/
│   ├── 0.16.0.md
│   ├── 0.16.0.zh.md
│   ├── hugo-upgrade.md
│   └── hugo-upgrade.zh.md
├── oink/
│   ├── implementation-diary.md
│   └── implementation-diary.zh.md
└── release/
    ├── 0.1.0.md
    └── 0.1.0.zh.md

A Docsy release note normally supplies a publisher-qualified linkTitle:

---
title: Release 0.16.0 report and upgrade guide
linkTitle: Docsy 0.16.0 release
date: 2026-07-29
tags: [release, upgrade]
---

Prefix link titles for other Docsy articles with Docsy as well, so mixed sidebar and list views make ownership clear.

Keep the publication date and author identity consistent across translations. Translate the title, description, taxonomy labels, caption text, and body. Do not translate commit IDs, release tags, commands, or URLs.

Working with top-level landing pages

Default-layout pages are suitable for the home page, product overview, and other destinations that do not need the docs sidebar.

Customizing the example site pages

The bundled home page is content/_index.md with content/_index.zh.md as its translation. It uses the same local assets and theme pipeline as the rest of OINK. Change content and project assets in the site; do not edit vendored runtime files merely to alter branding.

Building your own landing pages

Compose landing pages from standard Markdown and blocks/* shortcodes. Keep essential information in text, make call-to-action links meaningful, and test the page at mobile and desktop widths in both languages.

Adding a community page

Create community/_index.md and community/_index.zh.md. The community layout uses params.links.user and params.links.developer:

params:
  links:
    user:
      - name: User forum
        url: https://community.example.org/
        icon: fa-solid fa-comments
        desc: Ask questions and share solutions
    developer:
      - name: GitHub
        url: https://github.com/pgsty/oink
        icon: fa-brands fa-github
        desc: Source, issues, and pull requests

Entries may set rel; OINK also adds noopener to external HTTP links where appropriate. Set params.contributingUrl in the community page front matter if the contribution guide is not at the conventional docs route.

Adding static content

Files below static/ are copied to the published root without Markdown rendering or fingerprinting:

static/reference/api/index.html

is published as /reference/api/index.html. Use this for externally generated reference sites, verification files, and downloads that require stable names. Prefer page resources or Hugo Pipes for assets that need resizing, fingerprinting, or bundle-relative lookup.

OINK’s browser runtime is intentionally shipped from the theme or site itself. When adding a library, vendor and pin it, record it in VENDOR.json, and do not introduce an implicit CDN fallback.

RSS feeds

Hugo creates feeds for the home page and list sections. Disable them globally only when the site has no feed consumers:

disableKinds: [RSS]

If a section declares custom outputs, retain RSS explicitly:

outputs:
  section: [HTML, RSS, print]

Check the generated language-specific feed URLs and ensure titles, summaries, dates, canonical URLs, and hreflang relationships are correct.

Sitemap

Hugo generates sitemap.xml by default. Site-wide settings are:

sitemap:
  changefreq: monthly
  filename: sitemap.xml
  priority: 0.5

A page can override these values:

---
title: Release notes
sitemap:
  priority: 0.8
---

Treat changefreq and priority as hints, not promises. Exclude drafts, private material, and noncanonical duplicates before deployment, then inspect the generated sitemap for every published language.

3.3 - Organize your content

Oink derives the documentation sidebar from Hugo’s content tree. The directory structure is therefore part of the reader experience, not just a source-code detail. Start with the questions readers need answered, then create the smallest hierarchy that makes those answers easy to find.

Start from reader goals

Give new readers a short path from product context to a successful first task. Give returning readers direct routes to procedures, reference material, and troubleshooting. A practical documentation set usually needs:

• an overview that establishes scope and product boundaries;
• a get-started path that produces a working result;
• task-oriented guides for common jobs;
• reference pages for parameters, APIs, and compatibility;
• troubleshooting for predictable failure modes.

Examples are useful when readers can copy or compare them, but they should not replace the procedure or reference that explains the behavior.

Use predictable content types

Keep pages focused on one reader intent:

Do not create an empty top-level section merely to mirror an organization chart. Add a section when several pages share a stable reader purpose.

Keep the hierarchy shallow

Prefer a short, explicit route over a deep classification tree. Use page weights to establish a learning sequence, and keep related page weights spaced consistently so new pages can be inserted without renumbering the entire section. Add an icon and concise description to every navigable page so the sidebar and section indexes remain scannable.

See Adding content for Hugo’s bundle and section model, and Navigation and menus for sidebar behavior.

Plan languages together

Create the English source and Simplified Chinese peer in the same directory. Keep page order, intent, examples, and stable heading IDs aligned. If the two languages need different prose lengths, preserve the same information rather than forcing sentence-for-sentence symmetry.

Review the complete route

After moving or adding pages, review the documentation landing page, section index, sidebar, breadcrumbs, previous/next navigation, local search, and every homepage link. Build both languages and validate rendered fragment links before publishing.

3.4 - Hugo authoring tips

Oink is a Hugo theme, so ordinary Markdown and Hugo’s content model remain the authoring foundation. These conventions keep pages readable in source form and stable after translation, reorganization, or subpath deployment.

Link to published routes

Link readers to the canonical published URL, not to a neighboring source-file path. Root-relative links such as /docs/content/ are easy to audit across the site. When a link should follow a page through source moves, Hugo’s ref and relref shortcodes can resolve the target page:

[Configuration]({{</* ref "/docs/content/configuration" */>}})

After moving a page, add an alias for the old public route and update every internal link to the new canonical route. Do not rely on the alias as the site’s permanent navigation path. See Adding content for link and image behavior.

Keep front matter useful

Every navigable page needs a clear title, concise description, intentional weight, and suitable Font Awesome icon. Keep descriptions to one sentence that fits on one line in a normal desktop content card. Add linkTitle only when the navigation label genuinely needs to differ from the page title.

English is the primary source language. Add the Simplified Chinese peer beside it as .zh.md, and translate reader-facing metadata as carefully as the body.

Preserve stable headings

Use explicit heading IDs when pages are translated or widely linked:

## Failure recovery {#failure-recovery}

Copy the same ID to the corresponding Chinese heading. When renaming a heading, preserve an established ID unless its meaning also changes.

Write procedures as tasks

State prerequisites before commands, use imperative steps, and show the expected result or verification command. Separate local preview, production build, hosted deployment, and public release evidence; success at one layer does not establish the next.

Make code examples actionable

Name a block when it represents a real file, use console for a transcript with prompts and output, and collapse long reference listings that readers do not need to scan before continuing. Use a Code Group only when panels are interchangeable ways to complete the same task.

params:
  offlineSearch: true
  print:
    disable_toc: false

Metadata should clarify an example, not decorate every fence. See Code blocks and Code Groups for filenames, Copy policies, wrapping, collapse, line links, and synchronized alternatives.

Review rendered states

Build both languages and inspect representative pages on desktop and mobile, in light and dark modes. Verify headings, fragments, code, tables, alerts, navigation, search, print output, and page descriptions in the rendered site.

3.5 - Navigation and menus

OINK combines Hugo’s content tree and menu model with a documentation workspace: a global navbar, a collapsible and resizable section sidebar, and a collapsible page outline. The same structure works for English, Chinese, and right-to-left languages.

Site navbar

The global navbar is built from Hugo’s main menu plus OINK-generated controls. Depending on configuration and page type, it can include version, language, color-mode, and search controls.

Adding main menu entries

Define a menu entry in page front matter:

---
title: Documentation
linkTitle: Docs
menu:
  main:
    weight: 20
    pre: <i class="fa-solid fa-book" aria-hidden="true"></i>
---

Lower weights appear first. A site-level external link is similar:

menus:
  main:
    - name: GitHub
      identifier: github
      weight: 50
      url: https://github.com/pgsty/oink
      pre: <i class="fa-brands fa-github" aria-hidden="true"></i>

Use an identifier for configuration that refers to a menu item. Localize name or linkTitle in language configuration, but keep identifiers stable.

Version menu

The selector appears when params.versions is configured. Each entry can be a heading, separator, release, development build, or site variant:

params:
  version: v1.0.0
  version_menu: v1.0.0
  version_menu_pagelinks: true
  versions:
    - version: v1.1.0-dev
      kind: next
      url: https://next.example.org/
    - version: v1.0.0
      kind: latest
      url: https://docs.example.org/

version identifies the published site variant and is not necessarily a Git ref. Commands that require a resolvable tag should use the project’s explicit release-ref parameter instead. With page links enabled, OINK first tries the equivalent path on the target version and otherwise uses its configured URL.

Language menu

OINK builds language targets from Hugo’s AllTranslations. When a translated peer is missing, the target language’s home page is used instead of a broken URL. One configured language hides the control. With two or more languages, a click advances to the next language by weight, while hovering for half a second or focusing the control opens the complete menu. The current site cycles from English to Simplified Chinese and back. Targets include lang, hreflang, locale, and text-direction attributes.

Light/dark theme menu

When color-mode support is enabled, the navbar and documentation workspace show a theme control. See Light/dark-mode menu.

Search box

The documentation workspace uses a local search dialog when offline search is enabled. The sidebar button advertises the platform shortcut (Command/Ctrl+K). Online search integrations remain available by explicit configuration. See Search.

Adding icons to the navbar

Use pre or post on a menu entry. OINK includes the free local Font Awesome assets:

menus:
  main:
    - name: Source
      identifier: source
      url: https://github.com/pgsty/oink
      weight: 50
      pre: <i class="fa-brands fa-github" aria-hidden="true"></i>
      post: <span class="visually-hidden"> (external)</span>

Decorative icons need aria-hidden="true"; the link itself must retain a useful text or accessible label. External links that open a new tab must use rel="noopener".

Side navigation

The left panel on docs and blog pages is generated from the content hierarchy. OINK orders entries by weight and uses linkTitle when present. Sections come from _index.md files; translated sections need a peer _index.zh.md so their navigation metadata is localized.

Hide a page from the sidebar with:

toc_hide: true

Hide it from a section landing-page summary with hide_summary: true. Set both only when the page should be absent from both discovery surfaces.

Side-nav options

The common controls are:

params:
  ui:
    sidebar_menu_compact: true
    sidebar_menu_foldable: true
    sidebar_menu_truncate: 128
    sidebar_cache_limit: 2000
    sidebar_search_disable: false
    sidebar_width_min: 220
    sidebar_width_max: 480
    sidebar_item_overflow: ellipsis

• sidebar_menu_compact shows the active branch and nearby entries.
• sidebar_menu_foldable lets readers expand or collapse sections.
• sidebar_menu_truncate limits entries and emits a build warning when the limit is too small.
• sidebar_cache_limit enables shared navigation markup above the configured site size.
• sidebar_width_min and sidebar_width_max clamp the desktop drag-resizer.
• sidebar_item_overflow is ellipsis by default; use wrap for long labels.

The reader’s collapse state, width, and scroll position are preserved locally. The mobile view becomes a dismissible drawer with a backdrop and focus-safe controls.

Adding icons to the side nav

Set icon in page front matter:

---
title: Operations
icon: fa-solid fa-screwdriver-wrench
---

Use icons consistently across siblings. They are secondary cues, not a replacement for text labels.

Adding manual links to the side nav

Create a placeholder page at the desired position:

---
title: API status
weight: 90
manualLink: https://status.example.org/
manualLinkTitle: Live service status
manualLinkTarget: _blank
---

Use manualLinkRelref instead of manualLink for an internal content reference; Hugo then fails the build if it cannot resolve the destination. OINK adds noopener for new-tab links. Include a short body explaining the destination because Hugo still generates a page for the placeholder.

Section as sidebar root (EXPERIMENTAL)

Enable rooted sidebars:

params:
  ui:
    sidebar_root_enabled: true
    sidebar_root_menu: true

Then set a section’s _index.md:

---
title: API Reference v2
sidebar_root_for: self
sidebar_root_link_self: true
---

self applies the root to the section index and descendants; children keeps the index in the parent tree but roots its descendants. The optional root menu lets readers switch between roots. Rooted sections can nest, but redundant or invalid values produce build warnings.

Table of contents (TOC)

Hugo builds the right-side page outline from Markdown headings. OINK renders it as a fixed documentation panel with quick links, language and theme controls, repository metadata, and taxonomy terms. Readers can collapse the panel; its state is stored locally.

Headings emitted by Markdown shortcodes ({{%/* ... */%}}) participate in Hugo’s table of contents. Headings emitted only by standard shortcodes ({{</* ... */>}}) generally do not, so content structure should remain in Markdown whenever possible.

TOC customization

Hide the outline on one page:

notoc: true

Configure which heading levels Hugo includes:

markup:
  tableOfContents:
    startLevel: 2
    endLevel: 4
    ordered: false

Localize labels such as toc_on_this_page in the site’s i18n bundle. If custom CSS changes the outline rail or fixed-panel dimensions, test active tracking, zoom, keyboard focus, and pages with no headings.

Active TOC entry tracking with ScrollSpy

OINK uses a local Bootstrap ScrollSpy patch and IntersectionObserver to track the active heading. The workspace draws a continuous rail, active segment, and position marker. Disable tracking for a page with:

params:
  ui:
    scrollSpy:
      disable: true

The legacy ScrollSpy configuration also accepts a global rootMargin. Changing it affects when an entry becomes active and should be tested with short sections, long sections, and direct fragment navigation.

Advanced ScrollSpy customization

Prefer configuration and project CSS. Overriding the ScrollSpy attribute partial or docs-shell.js creates an implementation-level fork; add browser fixtures for hash updates, back/forward navigation, resizing, reduced motion, and pages that contain duplicate or missing IDs.

Breadcrumb navigation

Breadcrumbs are shown above ordinary content pages and in taxonomy results. Disable them globally:

params:
  ui:
    breadcrumb_disable: true
    taxonomy_breadcrumb_disable: true

The same ui.breadcrumb_disable value can be set in a page or section cascade. Breadcrumb labels come from localized page titles and must follow the same logical hierarchy as the sidebar.

Heading self links

Enable OINK’s heading render hook in a consuming site:

{{ partial "td/render-heading.html" . }}

The generated .td-heading-self-link control uses # by default. It remains visible on touch devices and appears on hover or focus for pointer devices. Keep the link keyboard reachable and preserve a scroll offset that clears fixed navigation.

Heading aliases and in-page targets

Changing a heading can break inbound fragment links. Treat its ID as a public route. To rename an ID, retain the old one as an empty anchor and set the new one explicitly:

## Quickstart <a id="get-started"></a> {#quickstart}

Use an empty <a id="..."></a> for an alias or other in-page target. Do not use a span solely as a fragment target. IDs must be unique, stable, ASCII where practical, and identical across language variants.

Quickstart

This live heading demonstrates that both #get-started and #quickstart reach the same location. Translated headings should write the English rendered ID explicitly rather than relying on language-specific automatic slug generation.

Implementation notes

• The document sets a global scroll offset for fixed chrome.
• Built-in block targets use td-anchor-no-extra-offset to avoid applying the additional offset twice.
• The translation audit compares rendered heading IDs between English and Chinese pages.
• Removing an old alias is a breaking documentation change and needs a redirect or an explicitly documented compatibility decision.

3.6 - Look and feel

OINK ships a complete visual system built on Bootstrap and Docsy, with local fonts, icons, styles, and browser code. A consuming site can change tokens and project styles without rebuilding a Node dependency tree.

Project styles

Hugo Extended compiles the theme’s SCSS through Hugo Pipes. Project overrides participate in the same bundle, so production builds can minify, fingerprint, and integrity-check one same-origin stylesheet.

Project style files

Override these files in the site’s assets/scss/ directory:

Start with the smallest override:

// assets/scss/_variables_project.scss
$primary: #315f8f;
$secondary: #b4762e;

// assets/scss/_styles_project.scss
body.td-blog {
  --td-body-font-family: 'Noto Serif', 'Noto Serif SC', serif;
}

Do not edit vendored Bootstrap, Font Awesome, or local font files for ordinary branding. A theme update would overwrite those changes and obscure the dependency boundary.

Advanced style customization

For the stable customization layers, typography presets, semantic font roles, and content-scoped patterns, read Advanced customization.

OINK’s SCSS import order is:

1. Bootstrap functions;
2. project variables;
3. OINK defaults and Bootstrap;
4. post-Bootstrap project variables;
5. OINK components and local brand layer;
6. project styles.

Use variables or CSS custom properties for stable design decisions. Override a selector only when no token exists, and scope it to the smallest component. Inspect both light and dark output because many colors are theme-dependent.

⚠️ Resetting internal styles

OINK’s internal partials are not a public Sass API. Importing or suppressing individual internal files couples a site to repository layout and import order. If a product needs a fundamentally different shell, override a Hugo layout or maintain a deliberate theme fork instead of resetting the entire stylesheet.

Extra styles

For isolated third-party CSS, publish a local asset from a hook:

{{ $extra := resources.Get "css/extra.css" | minify | fingerprint }}
<link rel="stylesheet" href="{{ $extra.RelPermalink }}"
  integrity="{{ $extra.Data.Integrity }}" crossorigin="anonymous">

Put the template in layouts/partials/hooks/head-end.html. Prefer the project SCSS files when the rules belong to the site’s design system. Never use a remote stylesheet as an implicit fallback.

Colors and color themes

Bootstrap semantic colors and OINK brand tokens are available throughout the theme. Semantic names communicate intent better than literal colors.

Site colors

Set Bootstrap variables before compilation:

$primary: #315f8f;
$secondary: #b4762e;
$success: #2c7a4b;
$warning: #9a6700;
$danger: #b42318;

OINK’s canonical layer also exposes CSS properties such as --td-brand-elev, --td-brand-silk, --td-brand-copper, --td-brand-header-bg, and --td-brand-mark-gradient. Override them on :root and [data-bs-theme='dark'] as a pair:

:root {
  --td-brand-copper: #a66722;
}

[data-bs-theme='dark'] {
  --td-brand-copper: #e0a35c;
}

Light/dark color theme and mode support

Color theme is the palette used by a component; color mode is the site-wide light or dark state. OINK uses Bootstrap’s data-bs-theme="light|dark" attribute and stores an explicit reader choice in local browser storage. With no choice, it follows prefers-color-scheme.

Every custom component must define legible states for both modes, including hover, focus, disabled, selected, and code colors. Do not encode meaning by color alone.

Light/dark color modes

The default sample site enables color-mode support and shows the selector:

params:
  ui:
    showLightDarkModeMenu: true

The selector updates the document before normal interaction to limit a flash of the wrong theme. OINK’s script is local and does not contact an external service.

Choosing themes or color modes for your site

Use the default automatic behavior for most sites. Choose a forced mode only when the complete visual identity has been tested in that mode and readers do not need an alternative. Screenshots are not sufficient: check real text, tables, alerts, forms, diagrams, code, and focus indicators.

How to disable dark mode

To disable dark mode and hide the menu:

params:
  ui:
    showLightDarkModeMenu: false

The experimental value enable-only (experimental) enables theme-aware styles without showing a selector. Treat it as transitional because the configuration surface can change.

How to pick colors with good color-contrast

Meet WCAG contrast requirements in every component state. Test actual computed colors, including translucent layers over images. As a working minimum, normal text needs 4.5:1 contrast and large text needs 3:1; focus and non-text UI indicators also need adequate contrast. Automated tools catch common failures, but keyboard and visual review remain necessary.

Fonts

OINK does not fetch Google Fonts. Open Sans, Chakra Petch, IBM Plex Mono, and Font Awesome files used by the theme are stored locally. The legacy Sass variable $td-enable-google-fonts controls the bundled Open Sans faces despite its historical name.

Set typography in _variables_project.scss:

$td-enable-google-fonts: true;
$font-family-sans-serif: 'Noto Sans SC', 'Open Sans', system-ui, sans-serif;
$font-family-monospace: 'IBM Plex Mono', ui-monospace, monospace;

OINK also exposes build-time typography presets and runtime-independent semantic font roles. See Advanced customization for the complete public interface and examples that scope a font to blog, OpenAPI, or code-heavy pages.

If you add a font, subset and self-host it, include the required scripts, use font-display: swap, document its license in VENDOR.json, and test CJK fallback. Do not make page rendering depend on a font CDN.

CSS utilities

Bootstrap utility classes are available in Markdown with raw HTML and in layouts. Prefer semantic Markdown and OINK shortcodes for content; use utilities for small, presentational adjustments that remain understandable at different breakpoints. Project-wide patterns belong in _styles_project.scss.

Code blocks

OINK supports Hugo Chroma by default and a locally vendored Prism option. Choose one highlighter consistently; enabling both produces duplicate markup or styles. For filenames, Copy policies, wrapping, collapse, line anchors, and shareable Code Groups, see Code blocks and Code Groups.

Code highlighting with Chroma

Chroma runs during the Hugo build and requires no browser highlighter. Use a language identifier:

```go
fmt.Println("hello")
```

Basic Chroma style configuration

Configure markup in Hugo:

markup:
  highlight:
    guessSyntax: false
    noClasses: false
    lineNos: false

OINK expects class-based output so light and dark styles can differ. When regenerating a palette, keep the generated CSS local and review it against the brand background.

Light/dark code styles and more

The theme includes separate Chroma palettes under assets/scss/td/chroma/ and applies them by mode. Project overrides should target .chroma beneath the relevant theme attribute, not hard-code a global background.

Selecting console block content

Use console for terminal transcripts. OINK styles prompts and output for selection so readers can copy commands without decorative prompt text. Keep commands and their output on distinct lines, and never rely on color alone to distinguish them.

Code blocks without a specified language

An unlabelled fence renders as plain code. Use it only when no grammar applies, and label command sessions as console or bash instead of asking Chroma to guess.

Copy to clipboard

Copy buttons are enabled for Chroma unless params.disable_click2copy_chroma is true. Clipboard access requires a secure context in deployed browsers. The control must remain keyboard accessible and must not copy line numbers or prompts.

Code highlighting with Prism

Set:

params:
  prism_syntax_highlighting: true

to use OINK’s local prism.js and prism.css. This is a compatibility option for existing sites; Chroma is preferred for a browser-light build.

Code blocks with no language

Prism also treats unlabelled blocks as plain text. Add the correct language class rather than enabling heuristic detection.

Extending Prism for additional languages or plugins

Build and vendor the exact Prism bundle, replace the local files in a controlled theme change, record its version and license, and add a fixture that exercises the language or plugin. Do not pull Prism components from a CDN at runtime.

Navbar

OINK’s navbar contains the project identity, main menu, version and language selectors when applicable, color-mode control, and search. On small screens, overflowing primary items remain horizontally reachable.

Default look and feel

The navbar uses the local brand palette and a fixed minimum height.

On mobile

The brand and actions stay visible while the primary menu can scroll. Test long Chinese labels, 200% zoom, touch targets, focus order, and both page directions.

On desktop

The main menu expands inline; version, language, mode, and search controls stay grouped. Avoid enough custom entries to push controls outside the viewport.

Translucent over cover images

The blocks/cover shortcode marks the navbar as cover-aware. It starts translucent and gains the normal background as the page scrolls.

Customizing the navbar

Use configuration for behavior and project SCSS for presentation. Preserve the landmark, focus order, accessible labels, and responsive overflow behavior when overriding the navbar partial.

Navbar height

Override $td-navbar-min-height before theme styles compile. Re-test anchor offsets, sidebar height, mobile wrapping, and cover blocks because all depend on this value.

Background color/opacity

Set --td-navbar-bg-color or --td-brand-header-bg in both modes. If the background is translucent, validate contrast over every cover image and provide a solid scrolled state.

Setting the navbar light/dark color theme

A page can set ui.navbar_theme: dark in front matter or cascade when its cover requires light foreground controls. This changes navbar component styling; it does not force the whole site’s color mode.

Translucent over cover images

Disable translucency site-wide with:

params:
  ui:
    navbar_translucent_over_cover_disable: true

Prefer this when cover imagery is unpredictable or accessibility review cannot guarantee contrast.

Styling your project logo and name

Place logo partial overrides under layouts/partials/ and source assets under assets/ or static/. Provide meaningful alternative text for informative marks and an empty alternative for a purely decorative mark. SVGs must use a view box and inherit or define colors for both modes.

The OINK sample uses a text wordmark with a local gradient. Change the site title in language configuration and the visual tokens in project SCSS; do not replace brand text with an image when selectable text works.

Light/dark-mode menu

The selector appears when params.ui.showLightDarkModeMenu is true. Keep it in the shared navigation so its state applies consistently across languages and page types.

Alerts

Markdown alert types map to semantic OINK/Bootstrap styles. Customize .alert-* and the alert render hook only as a pair, retain a visible label or icon, and test links and inline code inside every background. See Adding Content for syntax.

Tables

Markdown tables receive responsive and theme-aware styles. Keep cells concise, use real header cells, add a caption in custom HTML when context requires one, and test horizontal overflow on mobile. A table should not be used to position unrelated content.

Customizing templates

Hugo resolves site layouts before theme layouts. Copy only the smallest partial that needs changing and compare it during upstream syncs; a full baseof.html override can silently miss future accessibility and asset-pipeline fixes.

Add code to head or before body end

Use layouts/partials/hooks/head-end.html for head additions and layouts/partials/hooks/body-end.html for scripts or closing integrations. Self-host assets, load them only on pages that need them, and keep production CSP compatible.

Adding a banner before page content

Override the relevant hook or content partial with a condition based on page parameters. A banner must not hide the page heading, trap keyboard focus, or shift anchor targets beneath the fixed navigation.

Adding custom class to the body element

Set body_class in page front matter or a section cascade:

---
body_class: product-reference
---

OINK appends the value to its generated body classes. Use a project-specific, semantic class name and never insert untrusted content into this field.

3.7 - Code blocks and Code Groups

OINK enhances Hugo’s ordinary fenced code blocks without replacing Chroma or requiring a browser highlighter. The server emits the complete code and shell; small page-scoped scripts only enable Copy, visual collapse, and tab state.

Enhanced fences

Add metadata in Hugo’s fence attribute list. A fence without attributes still receives the same responsive shell and its normal Copy default. filename adds a visible header; title is its compatible alias, and setting both is a build error. With neither, OINK uses a compact overlay instead of an empty title row.

Authoring

```yaml {filename="hugo.yml" copy="all" lineNos="table" hl_lines="4 7-9" wrap=false collapse=18}
params:
  offlineSearch: true
```

Live result

Rendered result

This block combines a filename, inline line numbers, a stable root ID, line links, and highlighted source lines. Line numbers begin at 12, while hl_lines still addresses the source lines inside the fence:

12markup:
13  highlight:
14    noClasses: false
15params:
16  offlineSearch: true
17  ui:
18    sidebar_menu_foldable: true

Shell parameters

Hugo generic class, safe data-*, aria-*, and global attributes remain on the .td-code root. Names beginning with data-td-code and data-language are reserved. OINK rejects event-handler and inline-style attributes. Use label to override a filename-derived accessible name; a generic aria-label together with label or filename is a build error.

Hugo options

The render hook continues to pass these options to Hugo:

• lineNos, lineNoStart, and anchorLineNos;
• hl_lines;
• tabWidth and style.

Class-based Chroma markup remains inside .highlight and .chroma, so existing token-level overrides keep working. The new stable outer element is .td-code; sites using direct-child selectors such as .td-content > .highlight should update those selectors.

The visible language label normalizes the common bash, sh, and shell lexer aliases to BASH. The original lexer value is still passed to Chroma and retained in data-language.

Diffs deliberately use Chroma’s standard diff lexer rather than a custom transformer:

Authoring

```diff {filename="hugo.yaml.diff"}
 params:
-  offlineSearch: false
+  offlineSearch: true
```

Rendered result

 params:
-  offlineSearch: false
+  offlineSearch: true

Copy semantics

Ordinary source defaults to copy="all". console and shell-session default to copy="command": only lines carrying Chroma prompt tokens are copied, and prompt/output tokens are excluded. Use copy="all" when a complete transcript is intentional. command on another language is a build error.

Copy preserves indentation, internal blank lines, and Unicode, removes line numbers, trims only trailing newline characters, and appends exactly one final newline. A session lexer that emits no prompt token reports a localized failure and copies nothing. Set params.disable_click2copy_chroma: true to hard-disable Copy for the entire site.

Copy is shown as a compact icon without adjacent text. Its localized label is still exposed to assistive technology and as a hover tooltip; success and failure also change the icon and update the live status message.

For a multi-line terminal command, include the continuation prompt (normally >) on every continued transcript line. Chroma classifies an unprompted line as output, so copy="command" deliberately excludes it.

The Copy action on this live session copies the two commands, not the prompts or output:

Authoring

```console {title="Terminal session"}
$ hugo version
hugo v0.164.0+extended darwin/arm64
$ hugo --gc --minify
Total in 742 ms
```

Rendered result

$ hugo version
hugo v0.164.0+extended darwin/arm64
$ hugo --gc --minify
Total in 742 ms

Wrapping and collapse

wrap=true changes presentation only; copied source is untouched. It is incompatible with Chroma’s table line-number layout because separately wrapped gutter and source cells would drift. Use inline line numbers or disable wrap. OINK fails the build instead of silently misaligning them.

collapse=N is progressive enhancement. The server always emits all source; the browser clips only after it can measure the Nth real Chroma line. Without JavaScript, in assistive technology, and in print, the listing remains complete. Reduced-motion preferences disable the height animation.

The first example wraps a long value without altering copied text:

Authoring

```text {filename="config/artifacts.env" wrap=true}
ARTIFACT_URL=https://downloads.example.com/releases/2026/08/oink-complete-offline-distribution-arm64.tar.zst
CHECKSUM=sha256:6d3dce4f7acb18f586469adcb80ab35f3e859f9837786e151cfbc2b3c0f587b2
```

Rendered result

ARTIFACT_URL=https://downloads.example.com/releases/2026/08/oink-complete-offline-distribution-arm64.tar.zst
CHECKSUM=sha256:6d3dce4f7acb18f586469adcb80ab35f3e859f9837786e151cfbc2b3c0f587b2

The second emits all lines on the server but initially shows six in a browser:

Authoring

```yaml {filename="hugo.yaml" collapse=6}
baseURL: https://docs.example.com/
title: Product Documentation
defaultContentLanguage: en
languages:
  en:
    label: English
    weight: 1
  zh:
    label: 简体中文
    weight: 2
params:
  offlineSearch: true
```

Rendered result

baseURL: https://docs.example.com/
title: Product Documentation
defaultContentLanguage: en
languages:
  en:
    label: English
    weight: 1
  zh:
    label: 简体中文
    weight: 2
params:
  offlineSearch: true

Stable IDs and line links

Set a page-unique explicit id when publishing line-number links. IDs cannot contain ASCII whitespace or control characters and cannot collide with another code component’s generated viewport, tab, panel, title, or line-anchor ID. OINK reports any such collision as a build error:

Authoring

```go {id="server-start" lineNos="inline" anchorLineNos=true}
func start() {}
```

Rendered result

1func start() {}

OINK derives unique line-anchor prefixes from that ID. Generated IDs are safe inside a page but depend on the block ordinal and are not a permalink contract; inserting an earlier fence can change them.

Code Groups

Use code-group when examples are alternatives rather than independent tabs:

Authoring

{{< code-group id="docs-install-client" sync="docs-package-manager" persist=false
    label="Choose a package manager" copy="all" >}}
  {{< code-tab title="npm" value="npm" lang="bash" >}}
npm install @example/client
  {{< /code-tab >}}
  {{< code-tab title="pnpm" value="pnpm" lang="bash" selected=true >}}
pnpm add @example/client
  {{< /code-tab >}}
  {{< code-tab title="yarn" value="yarn" lang="bash" >}}
yarn add @example/client
  {{< /code-tab >}}
{{< /code-group >}}