# Basic site configuration

> Configure an OINK site, languages, navigation, and local features.

---

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

---

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.

```yaml
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
  highlight:
    noClasses: false

params:
  offlineSearch: true
  github_repo: https://github.com/example/product-docs
  github_branch: main
  copyright:
    authors: Example Authors
    from_year: 2026
  ui:
    showLightDarkModeMenu: true
    sidebar_menu_foldable: true
    breadcrumb_disable: false

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    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:

```text
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.