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