Skip to content

Using OINK Starter

A short, sequential guide from clone to publication.

Using OINK Starter

A short, sequential guide from clone to publication.

This short book explains the starter itself. Read it once from beginning to end, then replace it with the long-form guide your project needs.

Contents

1 Preview the Site

Clone the repository and open a local home page in three commands.

OINK Starter is a Hugo Module site. Git downloads the source, Go resolves the pinned theme, and Hugo builds everything.

Prerequisites

Install Git, Go 1.27 or newer, and Hugo Extended 0.165.0 or newer. The word extended must appear in hugo version.

Three commands

git clone https://github.com/pgsty/oink-starter.git
cd oink-starter
hugo server

Open http://localhost:1313/. Chinese is under /zh/; French is under /fr/.

First proof

Change one sentence in data/home/en.yaml and confirm that the browser reloads. You now have a working editing loop.

2 Understand the Structure

Know which small set of files owns configuration, content, and deployment.

The starter keeps each responsibility in one obvious place.

The map

hugo.yaml          site identity, languages, and optional integrations
data/home/         one compact landing-page file per language
content/blog/      posts, design notes, and releases
content/docs/      the four-part documentation tree
content/book/      this sequential tutorial
.github/workflows/ GitHub Pages and Cloudflare Pages deployment

Navigation follows content

The menus.main front matter on each section root creates the top navigation and its dropdowns. The directory tree below Docs and Book creates their sidebars.

Translations stay together

English uses .md; Chinese and French peers use .zh.md and .fr.md. Keep the files side by side and use matching explicit heading IDs.

3 Make It Yours

Replace the identity and sample content without rebuilding the theme.

Most projects need only content changes and two configuration edits.

Change identity once

At the top of hugo.yaml, replace Project Name and https://example.org/. The YAML title anchor carries the name into all three languages.

Replace assets/icons/logo.svg and static/favicon.svg only when you have real project artwork.

Replace the home page

Edit data/home/en.yaml, zh.yaml, and fr.yaml. The sections list controls order; the named blocks below it provide the copy.

Replace sample content

Keep the directory structure, then rewrite or delete the example leaves. To rename a top-level menu entry, edit the corresponding translated _index files.

Enable integrations deliberately

hugo.yaml contains commented examples for repository links, Giscus, Google Analytics, colors, typography, sharing, and feedback. Uncomment only a complete configuration that you intend to operate.

4 Publish the Site

Use either supplied workflow and verify the real deployed routes.

The generated public/ directory is a static site. The repository includes two independent deployment paths.

GitHub Pages

In repository settings, choose Pages → Source → GitHub Actions. A push to main runs .github/workflows/github-pages.yaml; the workflow calculates the correct repository subpath automatically.

Cloudflare Pages

Create a Direct Upload Pages project, then add CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN as repository secrets. Set the repository variable CLOUDFLARE_PAGES_ENABLED to true for automatic deploys. The project name defaults to the repository name and can be overridden with CLOUDFLARE_PROJECT_NAME.

Verify production

Open /, /zh/, and /fr/; then test one Blog, Docs, and Book route in each language. Confirm search, language switching, dark mode, and a narrow mobile viewport.

Important

A successful local build, a pushed commit, a green workflow, and a correct public site are four separate checks.