Tutorial on OINK

Get started

Mon, 01 Jan 0001 00:00:00 +0000

OINK is a Hugo theme that ships its browser runtimes with the theme. A consuming site needs only Hugo Extended: no Node.js, no PostCSS, no CDN, and no remote theme asset download during the build.

What this chapter covers

Read these seven pages in order and you will have a deployable bilingual documentation site:

Prerequisites , 5 min: Install Hugo Extended and confirm the binary reports extended. Git and Go are needed depending on how you obtain the theme.

Prerequisites

Mon, 01 Jan 0001 00:00:00 +0000

The only required tool on the consumer side is Hugo Extended. Whether you also need Git and Go depends on how you obtain the theme.

Install Hugo Extended

Install 0.160.1 or newer. The project site currently validates against 0.164.0.

Follow Hugo’s installation guides for your platform, then check which binary is actually selected:

BASH

hugo version

The output must contain extended:

CONSOLE

$ hugo version
hugo v0.164.0+extended+withdeploy darwin/arm64
                  ^^^^^^^^

Standard Hugo has no embedded Sass compiler, cannot build the theme’s SCSS, and fails the build outright.

Install OINK

Mon, 01 Jan 0001 00:00:00 +0000

OINK is published as the Hugo Module github.com/pgsty/oink. Modules are the recommended method for every site — it is the only one where Hugo resolves the version, verifies checksums, and leaves an audit record in go.sum.

The other three methods exist for specific constraints: network isolation, a platform that requires a complete source tree, or an organization that reviews its own copy of the theme. They are covered under Other installation methods.

Create a site

Mon, 01 Jan 0001 00:00:00 +0000

This page builds a minimal bilingual site from scratch. For a reference that is already fully configured, see the project site instead.

Create the skeleton

BASH

hugo new site --format yaml my-docs
cd my-docs
hugo mod init github.com/example/my-docs
hugo mod get github.com/pgsty/oink@v0.4.1

Minimum configuration

Save the following as hugo.yaml. This is the smallest set that runs; each entry is explained in Basic configuration:

Basic configuration

Mon, 01 Jan 0001 00:00:00 +0000

Hugo reads site-level settings from hugo.yaml, hugo.toml, or hugo.json. The OINK project site uses YAML because multilingual menus and theme options are easier to read and review in that form.

This page covers the configuration a site needs to run. Navigation menus, multilingual details, and version management are in Site configuration.

Complete minimum configuration

title: Product Documentation
baseURL: https://docs.example.com/
defaultContentLanguage: en

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    title: Product Documentation
    menus:
      main:
        - { name: Docs, pageRef: /docs, weight: 10 }
        - { name: Blog, pageRef: /blog, weight: 20 }
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    title: 产品文档
    menus:
      main:
        - { name: 文档, pageRef: /docs, weight: 10 }
        - { name: 博客, pageRef: /blog, weight: 20 }

markup:
  goldmark:
    renderer:
      unsafe: true

params:
  offlineSearch: true
  github_repo: https://github.com/example/product-docs
  github_branch: main
  copyright:
    authors: '[Example Authors](https://example.org/)'
    from_year: 2026
  footer_center_info: 'Powered by [Oink](https://oink.pgsty.com)'
  ui:
    showLightDarkModeMenu: true
    sidebar_menu_foldable: true

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.160.1

Key parameters

baseURL , string , required: The real production address, including any subpath. Deploying to example.com/docs/ requires https://example.com/docs/, or every asset link points at the wrong location.

Start from the project site

Mon, 01 Jan 0001 00:00:00 +0000

pgsty/oink.pgsty.com is OINK’s bilingual example and regression site. It is deliberately more complete than a minimal consuming site — treat it as a reference, then delete what your product does not need.

This path suits you if you want a working bilingual structure immediately and do not mind deleting before editing. To control every setting from the start, use Create a site.

Clone and build

BASH

git clone https://github.com/pgsty/oink.pgsty.com.git product-docs
cd product-docs
hugo --gc --minify

The committed go.mod pins a public version of github.com/pgsty/oink, so a fresh clone builds as-is.

Container preview

Mon, 01 Jan 0001 00:00:00 +0000

Containers are not required — OINK only asks for Hugo Extended. They suit a team that wants a pinned toolchain, or that would rather not install Hugo on every workstation.

Build the image

FROM debian:bookworm-slim

ARG HUGO_VERSION=0.164.0
ARG GO_VERSION=1.25.5
ARG TARGETARCH

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl git \
    && curl -L -o /tmp/hugo.deb \
      "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.deb" \
    && apt-get install -y /tmp/hugo.deb \
    && curl -L -o /tmp/go.tgz \
      "https://go.dev/dl/go${GO_VERSION}.linux-${TARGETARCH}.tar.gz" \
    && tar -C /usr/local -xzf /tmp/go.tgz \
    && rm -rf /var/lib/apt/lists/* /tmp/hugo.deb /tmp/go.tgz

ENV PATH="/usr/local/go/bin:${PATH}"
WORKDIR /src
EXPOSE 1313
ENTRYPOINT ["hugo"]
CMD ["server", "--bind", "0.0.0.0", "--disableFastRender"]

BASH

docker build -t oink-hugo .

The image installs Go. This is not optional when the site

imports the theme as a Hugo Module — Hugo needs Go to resolve and download modules. Sites using the offline archive, a submodule, or a clone can drop Go and get a much smaller image.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Diagnosis starts from a clean production build:

BASH

hugo --gc --minify --logLevel info

A consumer build command should never invoke npm, PostCSS, or Autoprefixer, and should never download the theme’s browser assets. Seeing those in the log means an upstream Docsy workflow has leaked into the configuration.

Build issues

Hugo is not Extended, or is too old

BASH

hugo version

The output must contain extended and be at least 0.160.1.