Get started on OINK

Other setup options

Wed, 08 Dec 2021 00:00:00 +0000

The recommended installation uses the github.com/pgsty/oink Hugo Module. The following options change how Hugo obtains the same theme source; they do not change content or the Hugo-only build command.

Prerequisites

Every option requires Hugo Extended 0.160.1 or newer. Git options require Git, and Hugo Modules require Go. None of the options requires Node.js, npm, PostCSS, or Autoprefixer for the consuming site.

Option 1: complete release archive

The complete offline archive contains the theme, local browser runtimes, fonts, licenses, notices, vendor manifest, and checksums. It is the preferred input for air-gapped builds and the simplest way to preserve an exact distribution.

Run OINK in a container

Mon, 30 Jul 2018 00:00:00 +0000

A container is optional: OINK itself only needs Hugo Extended. Use a container when the team wants a pinned tool image or does not install Hugo on developer workstations.

Create the Hugo image

The following Dockerfile installs the currently validated Hugo Extended version from its release package. Keep the version aligned with the theme’s support matrix.

FROM debian:bookworm-slim

ARG HUGO_VERSION=0.164.0
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 \
    && rm -rf /var/lib/apt/lists/* /tmp/hugo.deb

WORKDIR /src
EXPOSE 1313
ENTRYPOINT ["hugo"]
CMD ["server", "--bind", "0.0.0.0", "--disableFastRender"]

Build it from the site root:

Basic site configuration

Wed, 08 Dec 2021 09:22:27 +0100

Hugo reads site-wide settings from hugo.yaml, hugo.toml, or hugo.json. The The Oink project site uses YAML because multilingual menus and theme options remain easy to scan and review.

Minimum configuration

The following excerpt shows the important structure for the Hugo Module.

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
  highlight:
    noClasses: false

params:
  offlineSearch: true
  github_repo: https://github.com/example/product-docs
  github_branch: main
  copyright:
    authors: Example Authors
    from_year: 2026
  ui:
    showLightDarkModeMenu: true
    sidebar_menu_foldable: true
    breadcrumb_disable: false

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

English has weight 1 and is the default language; Simplified Chinese has weight 2; additional languages follow. The language selector uses this order when a click cycles to the next language and when the full hover menu is rendered.

Troubleshooting and known issues

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

Start diagnosis from a clean production build:

hugo --gc --minify --logLevel info

The consumer command should not invoke npm, PostCSS, Autoprefixer, or download theme browser assets.

Build issues

Hugo is not Extended or is too old

Run hugo version. The output must include extended, and the version must be at least 0.160.1. If a shell, editor, CI runner, or container still selects an older binary, inspect its PATH and pinned tool configuration rather than installing another copy blindly.