Repository tour

This page goes through every file and directory of a pgsty/oink.pgsty.com clone: what must stay, what to replace with your own details, what belongs to the documentation site and can be deleted whole — plus a safe order to delete in.

The theme’s code is not in this repository. It is a Hugo Module pinned by go.mod and stored in Go’s module cache. This repository holds content, configuration, and a small number of site-level overrides.

Top-level structure

Not listed above: .gitignore, .gitattributes, .nvmrc, .npmrc, and the generated output excluded by .gitignore — public/ (build output), resources/ (Hugo’s resource cache) and node_modules/. That last group never enters version control.

There is no i18n/ in the repository: interface strings (“Previous”, “On this page” and the like) come from the theme’s 32 language files. To change one of them, create i18n/zh.yaml at the site root and write only the keys you override.

What to do with each entry

Deletion order

Delete the periphery first, then the content, then the data. Build after each step so a problem points back at one step.

1. Drop the scaffolding

   None of this takes part in rendering, and removing it affects no page.

   rm -rf tests scripts node_modules
   rm -f package.json package-lock.json playwright.config.mjs .nvmrc .npmrc
   rm -f AGENTS.md TRANSLATION.md CONTRIBUTING.md agent-docs.config.yml Makefile
   rm -f .github/workflows/site-checks.yml .github/workflows/browser-quality.yml

   After deleting scripts/ you must edit .github/workflows/pages.yml: remove the Set up Node.js and Verify advertised and pinned release match steps, or the deploy fails there.

2. Drop the example content

   content/docs/ is OINK’s own theme documentation and content/blog/ its engineering blog; neither has anything to do with your product.

   rm -rf content/docs
   mkdir -p content/docs
   rm -rf content/blog        # if you want no blog; otherwise keep one post as a template

   Edit menus.main under each language in hugo.yml at the same time: those entries point at paths such as /docs/tutorial and /blog/release that no longer exist. content/_index.md is the home page — keep it and replace the body with yours.

3. Trim the data

   The three groups under data/ feed the home page, landing pages and release pages. Keep the home page data and edit it; delete the other two if unused.

   rm -rf data/landing data/download

   data/home/en.yaml and data/home/zh.yaml decide which sections the home page has; each entry is explained in Home and landing pages. Deleting data/home/ entirely still builds, and the home page falls back to an ordinary content page.

4. Swap the identity

   Finally, change the site name, params.productionURL, params.github_repo and the brand parameters in hugo.yml to yours, replace the logo and favicon under static/, and delete the OINK-specific configuration: services.googleAnalytics, params.comments and the params.version* keys. The itemized list is in step 3 of Quick start.

Where the theme lives

The theme is referenced as a Hugo Module, and two places point at it:

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

require github.com/pgsty/oink v0.6.0

hugo.yml declares which theme to use, go.mod pins which version of it, and go.sum records that version’s checksums. All three files are committed. The theme source never enters your repository: Hugo downloads it into Go’s module cache, and hugo mod graph shows what actually resolved.

Upgrade to the newest version:

hugo mod get -u github.com/pgsty/oink

Pin to one version:

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

Both commands rewrite go.mod and go.sum. A production site pins a release tag rather than following main. What to check before and after an upgrade, and how to roll back, is in Upgrade.

Site overrides

Files under layouts/ shadow the theme’s files of the same name, following Hugo’s template lookup order. This site has only one kind:

• layouts/_shortcodes/*.html — the site’s own shortcodes. Product documentation that needs a shortcode with business meaning puts it here too.

Self-linking heading anchors come from the theme’s own _markup/render-heading.html; a site does not need to build that hook.

To change the shell (sidebar, footer, page end), override the narrowest partial rather than copying baseof.html wholesale — a copy has to be merged by hand at every theme upgrade.

Verify

Build after each deletion step so an error points at what you just removed:

hugo --gc --minify --printPathWarnings --panicOnWarning

Once the deleting is done, all of this should hold:

• The build ends with Total in … and no WARN or ERROR
• No navbar entry links to a deleted directory
• Headings still have their self-link anchors (the theme’s own heading render hook; the site needs no override)
• git status shows no public/ or resources/

Related

• Quick start — the full clone, configure and deploy path
• From scratch and other install methods — building from an empty directory instead of trimming
• Organizing content — how the content/ tree becomes the sidebar
• Configuration — every hugo.yml key and its default
• Upgrade — upgrading the theme module, and the migration toolkit