Get started

The recommended path for a new site starts from pgsty/oink-starter, not from a copy of this documentation and regression repository. The Starter is a public GitHub template: it pins OINK v1.0.0, builds as-is, and contains only neutral project content and deployment workflows.

Choose a path

Five-minute baseline

1. Install the tools

   Install Git, Go 1.27 or newer, and Hugo Extended 0.165.0 or newer. The Hugo output must contain extended:

   $ go version
   go version go1.27.0 darwin/arm64
   $ hugo version
   hugo v0.165.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

   For a repository you intend to keep, open the Starter and select Use this template, then clone the repository GitHub created for you. To evaluate the untouched original locally:

   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. A browser reload that shows both changes is the first useful proof that configuration, content, and the pinned theme are connected correctly.

Customize from shallow to deep

• Use OINK Starter — identity first, then languages, 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.

This order is deliberate. A site that first proves its build and content tree is easier to debug than one that changes languages, navigation, CSS, analytics, and hosting at the same time.

Publication gate

Before the first push, run the same warning-strict production build the Starter workflows use:

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

Success means the command ends with Total in …, prints no warning or error, and public/ contains the language roots and representative Docs, Blog, and Book routes. It does not yet prove deployment: a local build, a commit, a push, a green workflow, and correct public rendering are separate gates.

Next

Start with the complete Starter tutorial. If the template deliberately carries 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.