Basic site configuration

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.

 1title: Product Documentation
 2baseURL: https://docs.example.com/
 3defaultContentLanguage: en
 4
 5languages:
 6  en:
 7    label: English
 8    locale: en-US
 9    weight: 1
10    title: Product Documentation
11    menus:
12      main:
13        - name: Docs
14          pageRef: /docs
15          weight: 10
16        - name: Blog
17          pageRef: /blog
18          weight: 20
19  zh:
20    label: 简体中文
21    locale: zh-CN
22    weight: 2
23    title: 产品文档
24    menus:
25      main:
26        - name: 文档
27          pageRef: /docs
28          weight: 10
29        - name: 博客
30          pageRef: /blog
31          weight: 20
32
33markup:
34  goldmark:
35    renderer:
36      unsafe: true
37  highlight:
38    noClasses: false
39
40params:
41  offlineSearch: true
42  github_repo: https://github.com/example/product-docs
43  github_branch: main
44  copyright:
45    authors: Example Authors
46    from_year: 2026
47  ui:
48    showLightDarkModeMenu: true
49    sidebar_menu_foldable: true
50    breadcrumb_disable: false
51
52module:
53  imports:
54    - path: github.com/pgsty/oink
55  hugoVersion:
56    extended: true
57    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.

Content translations

Put translations beside each other:

content/
├── _index.md
├── _index.zh.md
├── docs/
│   ├── _index.md
│   ├── _index.zh.md
│   ├── install.md
│   └── install.zh.md
└── blog/
    ├── release.md
    └── release.zh.md

Keep route-affecting metadata aligned. Translate titles, descriptions, menu labels, summaries, tags, image alternatives, and visible shortcode strings. Use the English rendered heading ID as an explicit ID on each translated heading so that fragments remain stable across languages.

Local search and browser resources

offlineSearch: true enables the theme’s same-origin Lunr index and CJK fallback. The index is generated per language. Do not configure a public search service unless the site intentionally accepts that network dependency.

Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, and Infographic are provided locally and loaded per page. PlantUML and Draw.io are service-based exceptions: configure an approved endpoint explicitly or keep them disabled.

Branding and repository links

Set title, per-language titles, params.logo, repository URLs, copyright, and menus at the site layer. OINK does not add an oink.* configuration tree; it uses Hugo and compatible Docsy parameter locations.

Repository metadata enables edit, view, issue, and age information on content pages. Keep github_repo, github_project_repo, github_branch, and github_subdir consistent with the source layout.

Production defaults

• Use a real production baseURL, including any subpath.
• Keep online analytics, comments, Google CSE, Algolia, and remote embeds off unless they are an explicit product choice.
• Pin Hugo Extended and the theme release in CI.
• Run hugo --gc --minify as the production command.
• Keep LICENSE, NOTICE, and the vendor manifest in redistributed archives.

See the project site’s complete hugo.yaml for a buildable reference.