Basic configuration

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

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

Output formats

OINK forces no optional output format. A site declares what it wants:

outputs:
  home: [HTML, RSS, markdown, LLMS]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

Local runtimes

Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, and Infographic all ship with the theme and load according to what each page actually uses. A page that uses none of them receives none of their runtimes.

PlantUML and Draw.io are the exception: their normal workflow depends on a rendering service, so OINK provides no default endpoint. Enabling one without configuring an endpoint fails the build:

params:
  plantuml:
    enable: true
    svg_image_url: https://diagrams.internal.example/plantuml/svg/

This is deliberate: a failed build is better than silently sending content to a public service you never chose.

Production checklist

• Use the real production baseURL, including any subpath.
• Disable hosted analytics, comments, Google CSE, Algolia, and remote embeds unless each is an explicit product decision.
• Pin the Hugo Extended version and the theme version in CI.
• Use hugo --gc --minify as the production build command.
• Keep LICENSE, NOTICE, and VENDOR.json when redistributing an archive.

For a complete buildable reference, read the project site’s own hugo.yml.

Next steps

• Site configuration: menus, languages, versions
• Authoring: start writing documentation