站点基础配置

配置 OINK 站点、语言、导航与本地功能。

Hugo 从 hugo.yaml、hugo.toml 或 hugo.json 读取站点级设置。Oink 项目站点使用 YAML，因为多语言菜单和主题选项更便于浏览与评审。

最低配置

下面的节选展示了 Hugo Module 的关键结构。

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

英文权重为 1，也是默认语言；简体中文权重为 2；其他语言依次排列。直接点击语言按钮时会按此顺序切换，完整的悬停菜单也采用相同顺序。

内容译文

将译文并置存放：

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

会影响路由的元数据应保持一致。标题、描述、菜单标签、摘要、标签、图片替代文字和短代码中的可见字符串都需要翻译。每个中文标题都应显式使用英文页面实际渲染出的标题 ID，确保不同语言中的 URL 片段保持稳定。

本地搜索与浏览器资源

offlineSearch: true 会启用主题的同源 Lunr 索引和 CJK 回退。索引按语言分别生成。除非站点明确接受相应的网络依赖，否则不要配置公共搜索服务。

Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts 和 Infographic 都由主题本地提供，并按页面加载。PlantUML 和 Draw.io 属于依赖服务的例外：请显式配置获准使用的端点，否则保持禁用。

品牌与代码仓库链接

在站点层设置 title、各语言标题、params.logo、代码仓库 URL、版权和菜单。OINK 不新增 oink.* 配置树，而是沿用 Hugo 与兼容 Docsy 参数的位置。

代码仓库元数据用于在内容页提供编辑、查看、提交问题和内容年龄信息。请确保 github_repo、github_project_repo、github_branch 与 github_subdir 同源码布局一致。

生产默认值

使用真实的生产 baseURL，包括可能存在的子路径。
除非属于明确的产品决策，否则关闭在线分析、评论、Google CSE、Algolia 和远程嵌入。
在 CI 中固定 Hugo Extended 和主题版本。
使用 hugo --gc --minify 作为生产构建命令。
重新分发归档时保留 LICENSE、NOTICE 和 vendor 清单。

可构建的完整参考配置请查看项目站点的 hugo.yaml。