Site configuration on OINK

Configuration

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

OINK follows a “native first” configuration model. Site identity, languages, menus, outputs, taxonomies, markup, and modules stay in their Hugo-defined locations. Existing Docsy parameters remain where their semantics are useful. OINK adds only focused choices for behavior that cannot be inferred.

Configuration rules

Prefer Hugo configuration over a theme-specific duplicate.
Prefer an established Docsy parameter over an OINK synonym.
Put brand, content, repository, and UI choices in their semantic locations.
Keep internal vendor paths and template composition out of the public API.
Fail early for invalid values or a missing required endpoint.

There is no oink.enabled flag and no params.oink.* tree. Adding either would create a second theme mode and make every fix, test, and document ambiguous.

Navigation and menus

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

OINK combines Hugo’s content tree and menu model with a documentation workspace: a site navbar on every layout, a collapsible and resizable section sidebar, a collapsible page outline in the right rail, and a site footer. The same structure works for English, Chinese, and right-to-left languages.

The navbar is built from Hugo’s main menu plus OINK-generated controls: the version selector, the language selector, the color-mode control, search, and the project repository link. It renders on every layout — landing pages, docs, blog, Swagger, and taxonomy pages alike — so the same site-level navigation is one click away from anywhere.

Languages

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

OINK uses Hugo’s multilingual page model directly and introduces no site-specific domain convention or template assumption. This site treats English as the primary language and Simplified Chinese (zh) as the second.

Configure languages

defaultContentLanguage: en

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    title: Product Documentation
    params:
      description: Product guides and reference
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    title: 产品文档
    params:
      description: 产品指南与参考资料
      time_format_default: 2006年1月2日
      time_format_blog: 2006年1月2日

label , string , required: The name shown in the language selector, written in that language — 简体中文, not Chinese.

Versions

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

When a product has several supported releases, the documentation usually follows. OINK provides two things: a version switcher and an archived version banner.

How each version is deployed is up to you — commonly one subdomain or subpath per version, each built separately.

List the versions that should appear in the menu under params.versions:

params:
  version_menu: v2.1
  versions:
    - version: v2.1
      url: https://docs.example.com
    - version: v2.0
      url: https://v2-0.docs.example.com
    - version: v1.9
      url: https://v1-9.docs.example.com

version_menu , string: The label on the menu button, usually the current version.

Repository links and page information

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

OINK’s documentation and blog layouts can show links to the current page’s source repository. They live in the page actions menu at the end of the breadcrumb row:

View markdown opens the generated Markdown alternate when that output is enabled.
View edit history opens the source file’s commit history.
Edit this page opens an editable source view.
Create child page starts a new file below the current page and can use the site’s assets/stubs/new-page-template.md template.
Create documentation issue opens an issue against the documentation repository with page context.
Create project issue optionally targets a separate product repository.

The built-in URL patterns target GitHub-style repositories. Verify every action when using another compatible host, and override the relevant partial for a different URL scheme.

Site configuration on OINK

Configuration

Configuration rules

Navigation and menus

Site navbar

Languages

Configure languages

Versions

Version menu

Repository links and page information