Use the Oink theme on OINK

Before you begin

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

The consumer prerequisite is Hugo Extended. Git and Go are conditional on how the theme source is obtained.

Install Hugo Extended

Install version 0.160.1 or newer. The current validation baseline is 0.164.0. A release’s support matrix takes precedence when these values change.

Verify the selected binary:

hugo version

The output must contain extended. Standard Hugo cannot compile the theme’s SCSS. Use Hugo’s official installation guides for the platform and pin the same version in local development and CI.

Inspect the bilingual project site

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

The independent pgsty/oink.pgsty.com repository is the complete bilingual example and regression site. It is intentionally more comprehensive than a starter: use it as a reference, then keep only the content and configuration your product needs.

Clone the project site

After the Oink theme has a public release, clone and build the site directly:

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

The committed go.mod pins github.com/pgsty/oink. For local theme development, clone the theme as a sibling and use the workspace commands documented in the Oink quick start.

Create a new site: start from scratch

Wed, 08 Dec 2021 09:21:54 +0100

The independent bilingual project site is a useful reference. Use this procedure to create a smaller site with its own content structure.

Create the site skeleton

Run:

hugo new site --format yaml my-new-site
cd my-new-site

Initialize the site module and pin Oink:

hugo mod init github.com/example/my-new-site
hugo mod get github.com/pgsty/oink@THEME_REF

Add minimum configuration

Use this as hugo.yaml:

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

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

markup:
 goldmark:
 renderer:
 unsafe: true
 highlight:
 noClasses: false

params:
 offlineSearch: true
 ui:
 showLightDarkModeMenu: true
 sidebar_menu_foldable: true

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

Commit go.mod and go.sum. Do not add npm mounts or a PostCSS pipeline.