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.