Skip to content

Get started

Start from the official OINK Starter. Verify the local site, then customize content, language, brand, integrations, and deployment in that order.

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.

Requirements

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

  1. 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:

    $ go version
    go version go1.27.3 darwin/arm64
    $ hugo version
    hugo v0.168.0+extended+withdeploy darwin/arm64
    

    On macOS, brew install git go hugo supplies them. On Linux and Windows, use the official Hugo installation guide and Go downloads. Choose Hugo Extended.

  2. 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:

    git clone https://github.com/pgsty/oink-starter.git my-docs
    cd my-docs
    hugo server
  3. 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.

  4. Make one visible change

    Change the title and canonical URL at the top of hugo.yaml, then edit one sentence in data/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:

hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings

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:

Claude Code
mkdir -p ~/.claude/skills/oink-site
curl -fsSL https://oink.pgsty.com/skill.md -o ~/.claude/skills/oink-site/SKILL.md
Codex
mkdir -p ~/.codex/skills/oink-site
curl -fsSL https://oink.pgsty.com/skill.md -o ~/.codex/skills/oink-site/SKILL.md

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.