Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Get started

Start from the official OINK Starter. Verify the local site, then customize content, language, brand, integrations, and deployment in that order.

For a new site, start from pgsty/oink-starter, a public GitHub template that pins a published OINK release, builds out of the box, and includes neutral project content and deployment workflows without this repository’s regression test harness.

Requirements

OINK sites build with Git, Go 1.27.3 or newer, and Hugo Extended 0.168.0 or newer (using Hugo’s built-in Sass compiler — no Node.js, npm, or external Sass installation required).

Choose a path

Starting point Path Result
New documentation or project site OINK Starter A small three-language Docs, Blog, and Book site with two deployment workflows
Existing Hugo site From scratch Add the OINK module and required Goldmark settings without replacing content
Existing Docsy or older OINK site Upgrade Preserve content, migrate supported syntax, and review site overrides

Five-minute baseline

  1. Install the tools

    Install Git, Go 1.27.3 or newer, and Hugo Extended 0.168.0 or newer. The Hugo output must contain extended:

    $ go version
    go version go1.27.3 darwin/arm64
    $ hugo version
    hugo v0.168.0+extended+withdeploy darwin/arm64
    

    On macOS, brew install git go hugo supplies them. On Linux and Windows, use the official Hugo installation guide and Go downloads. Choose Hugo Extended.

  2. Create or clone the site

    If you intend to keep the repository, open the Starter and select Use this template. Then clone the repository that GitHub creates. To evaluate the original without changes, use these commands:

    git clone https://github.com/pgsty/oink-starter.git my-docs
    cd my-docs
    hugo server
  3. Open the baseline

    Open http://localhost:1313/. The default Starter also publishes Chinese at /zh/ and French at /fr/. Confirm that Docs, Blog, Book, search, language switching, and light/dark mode all work before editing anything.

  4. Make one visible change

    Change the title and canonical URL at the top of hugo.yaml, then edit one sentence in data/home/en.yaml. Reload the browser. If both changes appear, configuration, content, and the pinned theme are connected correctly.

Customize from shallow to deep

  • Use OINK Starter — choose languages first, then identity, home page, content, navigation, brand, integrations, and deployment.
  • Starter repository tour — which file owns each part of the site, what to replace, and what can be removed.
  • Writing pages — front matter, headings, links, images, drafts, and the page-end controls.
  • Components — add expression only after the content tree is stable.
  • Brand and appearance — logo, accent, typography, width, and CSS extension points.
  • Deploy — use the supplied GitHub Pages or Cloudflare Pages workflow, then verify the real public routes.

Verify the build and content tree before customizing languages, navigation, CSS, analytics, and hosting; changing one layer at a time makes failures easy to isolate.

Publication gate

Before your first push, run the same production build command used by the Starter workflows:

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

Confirm that the build exits cleanly with Total in … and that public/ contains the language roots along with representative Docs, Blog, and Book routes. Keep warnings visible for review and do not enable --panicOnWarning or HUGO_PANICONWARNING (Hugo’s built-in LibSass deprecation notice is expected). After pushing, check the CI workflow and the live URL as well.

Build with an AI agent

OINK publishes an agent skill, Oink 建站 (oink-site): one Markdown file that packages the site-building workflow, the review standards of OINK’s own sites, and lessons from the case library. It defers to this documentation for syntax and asks the agent to verify its work in a browser.

Save it as a skill, then start a new agent session:

Claude Code
mkdir -p ~/.claude/skills/oink-site
curl -fsSL https://oink.pgsty.com/skill.md -o ~/.claude/skills/oink-site/SKILL.md
Codex
mkdir -p ~/.codex/skills/oink-site
curl -fsSL https://oink.pgsty.com/skill.md -o ~/.codex/skills/oink-site/SKILL.md

Then describe the site you want, for example “Use the oink-site skill to build a bilingual documentation site for this project.” An agent without a skills directory can follow the file directly when you give it the URL. Run the download again to update; the file states the OINK release it was written for.

Next

Start with the complete Starter tutorial. If the template has more structure than your project needs, use the repository tour to remove it safely. Use From scratch only when adding OINK to an existing site or when you explicitly want to assemble every file yourself.

1 - Use OINK Starter

Create your project site from the official Starter. Change one part at a time: languages, identity, home page, content, navigation, brand, integrations, and deployment.

pgsty/oink-starter is the official template for new OINK sites. It stays lean and clean, without this site’s theme reference docs, analytics IDs, comment repo settings, browser test harness, or PGSTY branding.

You only need Git, Go 1.27.3+, and Hugo Extended 0.168.0+ (which includes its built-in Sass compiler — no Node.js or external Sass installation required).

What the template contains

Surface Included baseline First decision
Languages English, Simplified Chinese, French Keep all three, or select a supplied single/bilingual profile
Content Docs, Blog, and a short Book tutorial Rewrite the examples. Delete a whole surface only if you do not need it
Home One compact data/home/<lang>.yaml per language Replace the project promise and destinations
Brand Neutral logo and favicon Keep them until real project artwork exists
Integrations Repository, Giscus, analytics, share, and feedback examples are commented Enable only complete configurations you intend to operate
Deployment GitHub Pages and Cloudflare Pages Direct Upload workflows Choose one production path and verify its real URL

The Starter’s own Book at /book/ is a four-chapter tour from preview to deployment. This page gives maintainers more detail. It explains the order of changes, their boundaries, and the checks after each group of changes.

Create your repository

GitHub template, recommended

Open the Starter repository, select Use this template → Create a new repository, then clone the repository created under your account or organization:

git clone https://github.com/OWNER/PROJECT-DOCS.git
cd PROJECT-DOCS
hugo server

This creates your site’s own Git history. The original Starter remains an upstream reference rather than a remote for pushes.

Clone the original to evaluate it

For a disposable local evaluation:

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

Do not start a real project by deleting this clone’s .git directory. GitHub’s template operation already creates a separate project and preserves an auditable first commit.

Preview before changing anything

Open these routes:

  • /, /zh/, /fr/ — the three home pages;
  • /docs/, /blog/, /book/ — the three content surfaces;
  • one translated page, then the language switcher;
  • search and the light/dark control at a narrow viewport.

Also record the resolved module:

hugo mod graph | grep github.com/pgsty/oink

Check the version supplied by your Starter snapshot in go.mod. To use the current release, update it to github.com/pgsty/[email protected] before customizing content:

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy

Customize in layers

Layer 1: language profile

The root configuration enables English, Chinese, and French. Before making other configuration edits, choose one of the supplied profiles when that is not your intended language set. Choose one of these commands:

cp examples/hugo.single.yaml hugo.yaml     # English only
cp examples/hugo.bilingual.yaml hugo.yaml  # English + Chinese

These are complete minimal configurations. Copying one replaces the commented integration examples in the root file. Copy it before other changes. If hugo.yaml already contains project changes, merge the languages and disableLanguages sections. Do not overwrite the file.

If you already changed the title and URL in Get started, keep that file. To change the default three-language setup to English and Chinese, add only disableLanguages: [fr] at the top level. For English only, use [zh, fr]. This preserves the identity and integration settings you have already changed.

Disabled languages stay declared so Hugo recognizes .zh.md and .fr.md as translations and safely ignores them. If you remove a language permanently, remove its content and home data only after the selected profile builds.

Layer 2: identity

Change the two marked values at the top of hugo.yaml:

hugo.yaml
title: &siteTitle Project Name
baseURL: https://example.org/

The YAML anchor carries the title to all enabled languages. Then change the copyright holder and, after the new repository exists, uncomment its links:

hugo.yaml
params:
  copyright:
    authors: '[Project contributors](https://example.org/community/)'
    from_year: 2026
  github_repo: https://github.com/OWNER/PROJECT-DOCS
  github_branch: main

Run hugo server again and check the browser title, footer, edit/history links, and canonical URL. Change the logo only if the project has final artwork. Review the text identity first.

Layer 3: home page

Home-page content lives in language data files under data/home/:

data/home/en.yaml
data/home/zh.yaml
data/home/fr.yaml

Edit one language first. In each file, sections sets the section order while hero, cards, and cta supply the content. Replace the tagline, destination URLs, and sample card text while keeping the structure intact, then translate the updated copy into each enabled language.

For additional section types, see Home and landing pages. The theme renders these data files directly—no layout override is needed.

Layer 4: content and navigation

Rewrite or remove sample leaf pages under content/. Keep section roots until you decide whether that whole surface belongs in your project:

content/docs/  reference and task documentation
content/blog/  posts, design records, and release announcements
content/book/  a sequential long-form guide

The content tree becomes the sidebar. menus.main on the translated _index roots controls top navigation. Rename Docs, Blog, or Book beside its content. There is no second global menu tree. Keep translated files side by side and give corresponding headings the same explicit IDs:

page.md
page.zh.md
page.fr.md

Follow Organizing content before creating a custom navigation data file. The generated tree is enough for most sites.

Layer 5: brand and reader features

Replace assets/icons/logo.svg and static/favicon.svg when real assets are ready. Then enable the smallest useful configuration changes, one at a time:

hugo.yaml
params:
  ui:
    theme_color: '#245f94'
    typography: system
    image_zoom: true
    share: [mastodon, linkedin, email, copy]

For custom local fonts, use params.ui.fonts for family names or declare font files in site CSS. For layout, sidebar, search, and component settings, consult the Configuration reference rather than copying the much larger configuration of oink.pgsty.com.

Layer 6: integrations

The Starter leaves repository actions, Giscus, Google Analytics, feedback, and sharing off or commented. Enable an integration only after all of its required facts are known:

  • Repository links need the real owner, repository, and branch.
  • Giscus needs its repository/category names and immutable IDs.
  • Google Analytics needs a project-owned measurement ID.
  • Feedback records structured gtag events only if analytics is present.
  • Assistant links send the current URL to a third party. They require an explicit policy choice.

An incomplete optional block should remain commented. See Comments, Analytics and SEO, and Repository links for the operating boundary of each integration.

Build and deploy

Local production build

Before enabling a hosting workflow:

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

Keep build warnings visible for review and do not enable --panicOnWarning or HUGO_PANICONWARNING (the upstream LibSass deprecation warning is expected). Commit hugo.yaml, go.mod, and go.sum. Never commit generated public/, resources/, module caches, or a local module replacement.

GitHub Pages

The Starter already contains .github/workflows/github-pages.yaml. In Settings → Pages, select GitHub Actions as the source. A push to main builds with the pinned toolchain, asks GitHub for the correct project subpath, and publishes public/ through the Pages deployment API.

Cloudflare Pages

The supplied .github/workflows/cloudflare-pages.yaml uses Direct Upload. Create a Pages Direct Upload project, add CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, then run the workflow manually once. Set the repository variable CLOUDFLARE_PAGES_ENABLED=true for automatic deploys, and CLOUDFLARE_SITE_URL when the canonical address is not the default pages.dev domain.

For one project, choose either Direct Upload or Cloudflare Git integration. Do not use both. The complete host comparison and baseURL rules are in Deploy.

Verify and remove samples

Before you declare the site ready, complete these checks:

  1. Search for placeholders such as Project Name, example.org, OWNER, and PROJECT, then decide whether each remaining occurrence is intentional.
  2. Open every enabled language root and representative Docs, Blog, and Book pages on desktop and mobile.
  3. Confirm that language switching opens peer pages rather than the home page.
  4. Test search, dark mode, one component, Markdown output, print, 404, canonical URLs, and repository actions.
  5. Check the deployed workflow and the public URL separately from the local build.

Delete the sample Book or Blog only after removing its top-menu root and any home-page card that links to it. After you remove each whole surface, rebuild and review the diagnostics. This lets you identify which change caused a failure.

Next

Use the Starter repository tour as a file-level map, then continue with Writing pages and Configuration. For an existing site that should not inherit the Starter’s content model, use From scratch.

2 - Starter repository tour

Find the oink-starter files that control identity, languages, home, content, navigation, brand, deployment, and the pinned theme.

This page walks through the repository layout created from pgsty/oink-starter. go.mod pins the OINK theme as a Hugo Module, and Hugo caches the resolved theme source in the Go module cache rather than copying it into your repository.

Top-level map

oink-starter/

  • oink-starter/
    • hugo.yamlidentity, languages, outputs, parameters, module import
    • go.modsite module and exact OINK release
    • go.summodule checksums
    • examples/
      • hugo.single.yamlEnglish-only complete profile
      • hugo.bilingual.yamlEnglish + Chinese complete profile
    • data/
      • home/
        • en.yamlone compact landing page per language
        • zh.yaml
        • fr.yaml
    • content/
      • _index.mdlanguage home roots
      • _index.zh.md
      • _index.fr.md
      • docs/Introduction, Get Started, Tutorial, Reference
      • blog/posts, design records, release announcements
      • book/sequential tutorial about the Starter
    • assets/
      • icons/logo.svgprocessed project logo
    • static/
      • favicon.svgcopied unchanged to the site root
    • i18n/
      • fr.yamlStarter-specific French interface overrides
    • .github/workflows/
      • github-pages.yamlproduction build and GitHub Pages deployment
      • cloudflare-pages.yamlproduction build and Cloudflare Direct Upload
    • README.mdoperating summary for repository maintainers
    • LICENSEtemplate source license

Generated public/, resources/, .hugo_build.lock, and module caches contain build state. Git ignores them. They are not source files.

What to change first

Path Responsibility Initial action
hugo.yaml Identity, canonical URL, languages, outputs, theme features, optional integrations Change the two marked values. Choose a language profile before other edits
data/home/ Home-page promise, cards, calls to action Rewrite every enabled language after one language is approved
content/ All reader-facing material Replace example leaf pages. Keep each section root until you decide to remove the whole surface
assets/icons/logo.svg Processed logo Replace only with final artwork
static/favicon.svg Browser icon Replace together with the logo review
params.github_* in hugo.yaml Edit/history/new-page/issue links Uncomment only after the destination repository exists

What to keep

  • go.mod and go.sum pin and verify the template’s selected OINK release. Commit both. Record a later upgrade separately from this baseline.
  • The three Goldmark settings in hugo.yaml: native Steps, Cards, Fields, image attributes, and Book targets depend on them.
  • outputs: if you remove markdown, LLMS, or print, you remove the corresponding Markdown, agent-index, or print output.
  • fetch-depth: 0 in workflows if enableGitInfo stays on. Last-modified and contributor facts require repository history.
  • GOWORK: off and HUGO_MODULE_WORKSPACE: off in CI. A developer’s local workspace must not replace the published release under verification.

Optional surfaces

Docs, Blog, and Book are independent top-level surfaces. To remove one safely:

  1. Delete its content/<surface>/ tree.
  2. Remove any home-page card or link that targets it.
  3. Confirm that no other page links to it.
  4. Run a build that keeps warnings visible for review. Inspect the remaining top navigation.

Do not delete only translated section roots. This creates language-specific navigation and fallback behavior that can appear to be an error. Remove a surface in all enabled languages or document the asymmetry.

The two configuration profiles under examples/ are optional after the language decision. They are useful references, but the root hugo.yaml is the only active site configuration.

Content and navigation

Under Docs and Book, directory structure and weight form the sidebar and pager sequence. Top navigation comes from menus.main on section roots. A translated root repeats the same identifier, parent, and weight while translating visible labels.

The Starter intentionally demonstrates the Documentation System model:

  • Introduction explains what the project does and why.
  • Get Started helps a new user achieve a result.
  • Tutorial teaches a complete task.
  • Reference records exact supported behavior.

Rename or restructure these sections for your project. Keep the learning paths separate. Do not combine every type of answer in one tree.

Language model

English source files end in .md; Chinese and French peers end in .zh.md and .fr.md. Home data uses language keys under data/home/. The root profile declares the languages, their locale, order, and site description.

The single and bilingual profiles keep disabled languages declared. Hugo then recognizes unused suffixes as translations. It does not render several files to one English URL. Copy a profile only before you start project-specific configuration. After that, merge changes manually.

Where OINK lives

Two files establish the module boundary:

hugo.yaml
module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: '0.168.0'
go.mod
module github.com/OWNER/PROJECT-DOCS

go 1.27.3

require github.com/pgsty/oink v1.5.1

This example pins the current release, v1.5.1. Check the pin in your Starter snapshot and follow the upgrade guide if it is older.

hugo mod graph displays the resolved version. Production builds use the exact tag in go.mod, while HUGO_MODULE_REPLACEMENTS can point to a local checkout during theme development. Keep local module replacements out of Git.

Deployment files

The GitHub Pages workflow runs automatically on pushes to main. In repository settings, select GitHub Actions as the Pages source. The Cloudflare workflow runs manually, or automatically only after the repository variable CLOUDFLARE_PAGES_ENABLED=true is set. Its required account ID and API token remain repository secrets.

Keep only the workflows for deployment paths you use. For one project, choose either Cloudflare Direct Upload or Cloudflare Git integration. Do not run both as deployment checks.

Safe customization order

  1. Prove the untouched preview.
  2. Select languages, then change identity.
  3. Replace one home page and then its translations.
  4. Replace content and verify navigation.
  5. Change brand and reader features one group at a time.
  6. Enable complete external integrations.
  7. Run the production build.
  8. Deploy, then verify production independently.

If you own the repository, commit after each group of changes. This lets you identify the decision that caused a regression or needs a rollback.

Verify

hugo mod graph | grep github.com/pgsty/oink
hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings
git status --short

Confirm that the module graph names the pinned release. The build must succeed and its diagnostics must be reviewed; the upstream LibSass warning is accepted. Git status must contain source edits but no public/ or cache files. Before deployment, open each enabled language root and one route from each of Docs, Blog, and Book.

3 - From scratch and other install methods

Build a minimal OINK site in an empty directory. Compare four install methods: Module, submodule, offline archive, and pinned source copy.

This is the manual alternative to the recommended OINK Starter. It builds a minimal site in an empty directory. A small hugo.yml and one hugo mod get command create a single-language site you can preview. You must assemble the home page, example content, deployment workflow, and all component usage yourself.

For an existing Hugo site, use the short integration path below. For an existing Docsy site, see Upgrade.

The second half compares four install methods: Hugo Module, Git submodule, offline archive, and pinned source copy. Current development and builds use Go 1.27.3 and Hugo Extended 0.168.0 (with built-in Sass — no external Sass needed).

Add OINK to an existing site

Work on a branch with the site’s current configuration and content preserved. Skip hugo new site and keep the existing configuration filename.

  1. If the site has no go.mod, run hugo mod init with your repository’s module path. Otherwise keep the existing module declaration.
  2. Run hugo mod get github.com/pgsty/[email protected].
  3. Replace the old theme selection with the OINK module.imports entry shown below. Preserve unrelated imports and configuration. Merge the three markup.goldmark settings and markup.highlight.noClasses: false from the example. Do not replace your whole configuration with it.
  4. Review site-owned layouts/ and assets, old theme shortcodes, and page type/layout values. These overrides and conventions may still select the previous theme’s behavior. Keep content. Make only the necessary adaptations.
  5. Run hugo, then open an existing representative page with hugo server. Check its navigation, images, and code blocks before applying optional OINK features. Continue with verification.

From an empty directory to the first page

  1. Create the skeleton and fetch the theme

    hugo new site --format yaml my-docs
    cd my-docs
    git init
    hugo mod init github.com/example/my-docs
    hugo mod get github.com/pgsty/[email protected]

    After hugo mod init, specify your site’s module path. This is usually its repository address. hugo mod get writes go.mod and go.sum. Commit both.

    Before building, create .gitignore so generated files stay out of Git. Leave enableGitInfo off until you have made the first commit:

    .gitignore
    /public/
    /resources/
    /.hugo_build.lock
    /.hugo_cache/

    Find the latest release tag on GitHub Releases; v1.5.1 on this page reflects this site’s current pin. Production sites should pin an explicit release tag in go.mod rather than tracking main.

  2. Writing hugo.yml

    For this new site only, rename the generated hugo.yaml to hugo.yml (Hugo accepts both) and replace its contents with the following. Existing sites should merge the relevant settings instead:

    hugo.yml
    title: Product Docs
    baseURL: https://docs.example.com/
    defaultContentLanguage: en
    # enableGitInfo: true        # the "last modified" time comes from git; make the first Git commit before enabling
    
    languages:
      en:
        label: English
        locale: en-US
        weight: 1
        title: Product Docs
        params:
          description: Everything about running Product in production
        menus:
          main:
            - { name: Docs, pageRef: /docs, weight: 20 }
            - { name: Blog, pageRef: /blog, weight: 50 }
    
    # The three Goldmark prerequisites: OINK's native Markdown components depend on them
    markup:
      goldmark:
        renderer:
          unsafe: true # allow inline HTML in content
        parser:
          attribute:
            block: true # attribute lines such as {.steps} {.cards} {caption=}
          wrapStandAloneImageWithinParagraph: false # only a block-level image can carry an attribute line
      highlight:
        noClasses: false # code colours follow light and dark mode
    
    params:
      offline_search: true
      github_repo: https://github.com/example/product-docs
      copyright:
        authors: '[Example Inc.](https://example.com/)'
        from_year: 2026
      ui:
        dark_mode: true
        sidebar_menu_foldable: true
        section_index: cards
    
    outputs:
      home: [HTML, markdown, LLMS]
      page: [HTML, markdown]
      section: [HTML, RSS, print, markdown]
    
    module:
      imports:
        - path: github.com/pgsty/oink
      hugoVersion:
        extended: true
        min: '0.168.0'

    These five blocks control different parts of the site:

    Block Governs Consequence of omitting it
    Top level + languages Site name, domain, languages and navbar menu An incorrect baseURL makes every absolute production link incorrect
    markup.goldmark The three component prerequisites An attribute line becomes a literal {.steps} in the prose
    params Search, repository links, shell switches Interactive features stay off. The theme does not select them for the site
    outputs The per-page .md, llms.txt and print pages No “Copy as Markdown” in the page menu, and no print view
    module References the theme and declares the Hugo floor The build cannot find the theme

    Mathematics additionally needs Goldmark’s passthrough extension; see Math. For each key’s meaning and default, see Configuration.

  3. Write the first page

    Every top-level directory under content/ is a section. The directory structure determines the sidebar structure. A documentation section needs at least an _index.md:

    content/docs/_index.md
    ---
    title: Docs
    linkTitle: Docs
    description: Everything about running Product in production.
    weight: 20
    ---
    
    Start with [Install](/docs/install/).
    content/docs/install.md
    ---
    title: Install
    description: Install Product on a fresh machine.
    weight: 10
    ---
    
    ## Prerequisites {#prerequisites}
    
    > [!IMPORTANT]
    > Product needs PostgreSQL 18 or newer.
    
    ## Install {#install}
    
    ```bash
    curl -fsSL https://get.example.com | bash
    ```

    Write explicit {#id} anchors on headings. When you add a translation, the anchors in both languages must correspond. For page-writing instructions, see Writing pages.

  4. Preview

    hugo server

    Open http://localhost:1313/docs/. The Docs section lists Install. The home page is still empty until you add home content. Edit the Install page and confirm that the preview updates.

Other install methods

The steps above use a Hugo Module. The other three address specific constraints. These include network isolation, platforms that require the full theme tree as build input, and organizations that review their own theme copy. Apart from hugo mod vendor, none of them creates a Go module, and the site references the theme with theme: oink rather than module.imports. For these methods, you must manage version resolution and integrity checks.

Hugo Module (recommended)

hugo mod init github.com/example/product-docs
hugo mod get github.com/pgsty/[email protected]
hugo.yml
module:
  imports:
    - path: github.com/pgsty/oink

This is the only method in which Hugo resolves the version, verifies the checksum, and records it in go.sum. hugo mod graph shows the resolved version. hugo mod get -u upgrades it. This method requires Go on the machine.

Git submodule

Record an exact theme 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 v1.5.1
git add .gitmodules themes/oink
hugo.yml
theme: oink

Before CI runs Hugo, it must initialize the submodule. Otherwise, themes/oink is an empty directory:

git submodule update --init --recursive

Offline archive

For network-isolated environments, choose one of two paths. Prepare either archive on a connected machine. Transfer the complete archive.

With hugo mod vendor, the resolved theme source is frozen into the site directory, and later builds need neither the network nor Go.

hugo mod vendor          # writes _vendor/, holding the theme's full source tree
tar czf ../my-docs.tgz . # put the archive outside the directory being archived

If _vendor/ exists, Hugo prefers it. hugo mod graph prints +vendor. Keep module.imports in hugo.yml unchanged. This step requires Go. Later builds do not. Upgrading the theme means returning to a connected environment and running hugo mod get and hugo mod vendor again.

_vendor/ collects only the directories the theme mounts (assets, data, i18n, layouts, static) plus hugo.yaml and theme.toml. It does not include LICENSE, NOTICE or VENDOR.json. To redistribute that archive, take those three files from the theme repository as well.

With a tag source archive, no Go module is created. Unpack the selected theme version into themes/oink/.

curl -L -o oink.tar.gz \
  https://github.com/pgsty/oink/archive/refs/tags/v1.5.1.tar.gz
mkdir -p themes/oink
tar xzf oink.tar.gz -C themes/oink --strip-components=1
hugo.yml
theme: oink

The theme repository’s root is the module root. Unpacking places layouts/, assets/, i18n/, and static/ directly under the target. There is no additional directory level. Redistribution must keep LICENSE, NOTICE, and VENDOR.json. The manifest records each third-party runtime’s version, source, license path, and SHA-256. Use it for an offline audit.

When moving between machines, generate the archive and its checksum from an immutable tag on the connected side:

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

Carry the archive and its .sha256 into the isolated environment, verify the checksum, and unpack:

shasum -a 256 -c oink-v1.5.1.tar.gz.sha256
mkdir -p themes
tar -xzf oink-v1.5.1.tar.gz -C themes

Before building offline, confirm that all eleven top-level entries are present:

themes/oink/

  • oink/
    • go.modmodule path declaration, used when resolving as a Hugo Module
    • hugo.yamltheme default parameters and the Hugo version floor
    • theme.tomltheme metadata, required by the theme: oink method
    • LICENSEApache-2.0
    • NOTICEupstream attribution; must be kept on redistribution
    • VENDOR.jsonthird-party runtime manifest: version, source, licence path, SHA-256
    • assets/SCSS, JS and the third-party runtimes shipped with the theme
    • layouts/templates, partials, shortcodes, render hooks
    • static/font files, published as is
    • i18n/32 interface language files
    • data/the SPDX licence table behind the page-end attribution line

Pinned source copy

When a hosting platform needs the theme files in the site repository, use the tag archive procedure above and unpack it into themes/oink/. Set theme: oink and commit the extracted files together with the tag and checksum you verified.

A plain git clone ... themes/oink leaves a nested .git directory. Adding it to the parent repository records a Git link rather than the theme files. This does not provide a self-contained source copy. Use a submodule if you want Git to track the theme by reference.

The four methods compared

Method Needs Go Version auditable Theme source in your repository Use when
Hugo Module Yes go.sum verifies automatically No The default
Git submodule No The repository records the commit By reference The theme source has to be in the repository
Offline archive No Checksums verified by hand Yes Network isolation
Pinned source copy No Record the tag and checksum Yes The platform requires a complete tree
A consuming site needs no front-end toolchain

Bootstrap, Font Awesome, the fonts, and the search and diagram runtimes all ship with the theme. A site needs no node_modules, no PostCSS, no RTLCSS and no CDN. Tutorials that install npm dependencies for a Docsy site describe upstream Docsy’s process and do not apply to OINK.

Developing against a local theme checkout

This section applies only when changing the theme and the site together. Clone the two repositories as siblings:

sibling directory layout
~/pgsty/
├── oink/            # the theme
└── product-docs/    # your site

Use the HUGO_MODULE_REPLACEMENTS environment variable to substitute the local checkout temporarily, leaving go.mod untouched:

cd ~/pgsty/product-docs
HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> ../oink' hugo server

The documentation site’s Makefile runs these commands. make dev and make check expect the theme checkout at the sibling ../oink:

Makefile: as the documentation site writes it
build:
	hugo --cleanDestinationDir --minify

check:
	HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> $(abspath ../oink)' npm test

dev:
	HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> $(abspath ../oink)' hugo server --renderToMemory

A Go workspace (go work init plus HUGO_MODULE_WORKSPACE=go.work) is an equivalent alternative. Both apply only to the local machine. CI and production builds use the version in go.mod. Never commit go.work.

Verify

hugo mod graph                                       # which theme version actually resolved
hugo --gc --minify --printPathWarnings

It passes when the build ends with Total in … and no unexpected WARN or ERROR (the upstream LibSass deprecation warning is expected; keep warnings visible for review and do not enable --panicOnWarning or HUGO_PANICONWARNING). Then confirm:

  • /docs/ opens and the sidebar holds the page you wrote
  • The navbar has a search box that finds the heading you just wrote
  • The light/dark toggle is present. Code block colors change with it, which confirms markup.highlight.noClasses: false took effect
  • git status --short lists only source changes. Git ignores generated output. For the Module path, commit both go.mod and go.sum. Other install methods keep their own theme source or submodule record.