About Oink

• 1: Example sites
• 2: Local-first operation
• 3: Architecture
• 4: Contribution guidelines
• 5: Release process
• 6: Open-source licenses and acknowledgements

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.

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.

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.

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.

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.

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.