# Basic configuration

> Site identity, languages, search, repository links, and production build flags.

---

LLMS index: [llms.txt](/llms.txt)

---

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](/docs/configure/).

## Complete minimum configuration {#minimum-configuration}

```yaml {filename="hugo.yaml" lineNos="table" collapse=28}
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 {#key-parameters}

- `baseURL` — `string`; required

  <p>The real
  production address, <strong>including any subpath</strong>. Deploying to <code>example.com/docs/</code>
  requires <code>https://example.com/docs/</code>, or every asset link points at the wrong
  location.</p>

- `defaultContentLanguage` — `string`; default: `en`

  <p>The
  default language. It decides which language the unprefixed URLs serve.</p>

- `languages.<lang>.weight` — `integer`

  <p>Language order. The lowest weight comes first, and the language button cycles in
  that order.</p>

- `params.offlineSearch` — `boolean`; default: `false`

  <p>Enables
  the theme&rsquo;s same-origin Lunr index and CJK substring fallback. Indexes are
  generated per language and queries never leave the site.</p>

- `params.github_repo` — `string`

  <p>The content repository.
  Edit this page, View edit history, and Report an issue are all derived from it.</p>

- `params.github_branch` — `string`; default: `main`

  <p>The
  branch that edit and history links point at.</p>

- `params.ui.showLightDarkModeMenu` — `boolean`; default: `false`

  <p>Shows the light/dark control. OINK&rsquo;s interactive features are opt-in; the theme
  does not set site policy on a site&rsquo;s behalf.</p>

## Output formats {#output-formats}

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

```yaml {filename="hugo.yaml"}
outputs:
  home: [HTML, RSS, markdown, LLMS]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]
```

| Format     | Effect                                                   |
| ---------- | -------------------------------------------------------- |
| `markdown` | Enables the Copy Markdown and View markdown page actions |
| `LLMS`     | Emits `llms.txt` so AI tooling can index the site        |
| `print`    | Enables the whole-section print view                     |

## Local runtimes {#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:

```yaml {filename="hugo.yaml"}
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 {#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 {#next-steps}

- [Site configuration](/docs/configure/): menus, languages, versions
- [Authoring](/docs/content/): start writing documentation