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
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