This is the multi-page printable view of this section. .
Get started
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.
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
-
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:On macOS,
brew install git go hugosupplies them. On Linux and Windows, use the official Hugo installation guide and Go downloads. Choose Hugo Extended. -
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:
-
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. -
Make one visible change
Change the title and canonical URL at the top of
hugo.yaml, then edit one sentence indata/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:
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:
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
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:
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:
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:
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:
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:
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:
The YAML anchor carries the title to all enabled languages. Then change the copyright holder and, after the new repository exists, uncomment its links:
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/:
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:
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:
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:
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
gtagevents 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:
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:
- Search for placeholders such as
Project Name,example.org,OWNER, andPROJECT, then decide whether each remaining occurrence is intentional. - Open every enabled language root and representative Docs, Blog, and Book pages on desktop and mobile.
- Confirm that language switching opens peer pages rather than the home page.
- Test search, dark mode, one component, Markdown output, print, 404, canonical URLs, and repository actions.
- 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
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
- home/
- 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.modandgo.sumpin 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 removemarkdown,LLMS, orprint, you remove the corresponding Markdown, agent-index, or print output.fetch-depth: 0in workflows ifenableGitInfostays on. Last-modified and contributor facts require repository history.GOWORK: offandHUGO_MODULE_WORKSPACE: offin 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:
- Delete its
content/<surface>/tree. - Remove any home-page card or link that targets it.
- Confirm that no other page links to it.
- 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:
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
- Prove the untouched preview.
- Select languages, then change identity.
- Replace one home page and then its translations.
- Replace content and verify navigation.
- Change brand and reader features one group at a time.
- Enable complete external integrations.
- Run the production build.
- 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
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.
Related
- Use OINK Starter — the complete layered workflow
- From scratch — add OINK without adopting this content model
- Organizing content — sidebar, pager, and menu authority
- Configuration — every current site parameter
- Deploy — host-specific setup and production checks
3 - From scratch and other install methods
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.
- If the site has no
go.mod, runhugo mod initwith your repository’s module path. Otherwise keep the existing module declaration. - Run
hugo mod get github.com/pgsty/[email protected]. - Replace the old theme selection with the OINK
module.importsentry shown below. Preserve unrelated imports and configuration. Merge the threemarkup.goldmarksettings andmarkup.highlight.noClasses: falsefrom the example. Do not replace your whole configuration with it. - Review site-owned
layouts/and assets, old theme shortcodes, and pagetype/layoutvalues. These overrides and conventions may still select the previous theme’s behavior. Keep content. Make only the necessary adaptations. - Run
hugo, then open an existing representative page withhugo server. Check its navigation, images, and code blocks before applying optional OINK features. Continue with verification.
From an empty directory to the first page
-
Create the skeleton and fetch the theme
After
hugo mod init, specify your site’s module path. This is usually its repository address.hugo mod getwritesgo.modandgo.sum. Commit both.Before building, create
.gitignoreso generated files stay out of Git. LeaveenableGitInfooff until you have made the first commit:.gitignoreFind the latest release tag on GitHub Releases;
v1.5.1on this page reflects this site’s current pin. Production sites should pin an explicit release tag ingo.modrather than trackingmain. -
Writing
hugo.ymlFor this new site only, rename the generated
hugo.yamltohugo.yml(Hugo accepts both) and replace its contents with the following. Existing sites should merge the relevant settings instead:hugo.ymlThese five blocks control different parts of the site:
Block Governs Consequence of omitting it Top level + languagesSite name, domain, languages and navbar menu An incorrect baseURLmakes every absolute production link incorrectmarkup.goldmarkThe three component prerequisites An attribute line becomes a literal {.steps}in the proseparamsSearch, repository links, shell switches Interactive features stay off. The theme does not select them for the site outputsThe per-page .md,llms.txtand print pagesNo “Copy as Markdown” in the page menu, and no print view moduleReferences 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.
-
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.mdcontent/docs/install.mdWrite explicit
{#id}anchors on headings. When you add a translation, the anchors in both languages must correspond. For page-writing instructions, see Writing pages. -
Preview
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)
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:
Before CI runs Hugo, it must initialize the submodule. Otherwise, themes/oink
is an empty directory:
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.
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/.
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:
Carry the archive and its .sha256 into the isolated environment, verify the
checksum, and unpack:
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 |
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:
Use the HUGO_MODULE_REPLACEMENTS environment variable to substitute the local
checkout temporarily, leaving go.mod untouched:
The documentation site’s Makefile runs these commands.
make dev and make check expect the theme checkout at the sibling ../oink:
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
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: falsetook effect git status --shortlists only source changes. Git ignores generated output. For the Module path, commit bothgo.modandgo.sum. Other install methods keep their own theme source or submodule record.
Related
- Get started — choose between Starter, an existing Hugo site, and migration
- OINK Starter — the recommended new-site path
- Starter repository tour — what each template directory owns
- Configuration — every
hugo.ymlkey and its default - Writing pages — how to keep writing after the first page
- Upgrade — upgrading the theme module, and migrating from Docsy