配置 on OINK

配置

Mon, 01 Jan 0001 00:00:00 +0000

OINK 遵循“原生优先”的配置模型。站点身份、语言、菜单、输出、taxonomy、标记与模块继续放在 Hugo 规定的位置；语义仍然适用的 Docsy 参数也保持原位。只有无法可靠推导的行为选择，OINK 才会增加职责明确的配置。

配置原则

优先使用 Hugo 配置，不创建主题专用的重复项。
优先使用成熟的 Docsy 参数，不另造 OINK 同义词。
品牌、内容、仓库与 UI 选项应放在各自语义位置。
内部 vendor 路径与模板组装方式不属于公开 API。
遇到非法值或缺少必需端点时，应尽早失败。

OINK 不提供 oink.enabled 开关，也不建立 params.oink.* 配置树。增加这些配置会制造第二套主题模式，让每项修复、测试和文档都产生歧义。

完整基线配置

以下示例把英文设为首要语言、简体中文设为第二语言：

YAML

title: Product Documentation
baseURL: https://docs.example.com/
defaultContentLanguage: en
enableRobotsTXT: true

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 }

outputs:
  home: [HTML]
  section: [HTML, RSS, print]

markup:
  goldmark:
    renderer:
      unsafe: true
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]
  highlight:
    noClasses: false

params:
  logo: icons/logo.svg
  offlineSearch: true
  offlineSearchIndex: summary
  offlineSearchMaxResults: 10
  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
    quick_links: [docs, blog]
    sidebar_menu_foldable: true
    sidebar_item_overflow: wrap
    breadcrumb_disable: false

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.160.1

模块版本固定在站点的 go.mod 中。使用传统主题 checkout 时，可以把仓库放在 themes/oink/，并改用 theme: oink。

导航与菜单

Mon, 01 Jan 0001 00:00:00 +0000

OINK 把 Hugo 的内容树和菜单模型组织成一套文档工作台：出现在所有布局上的站点导航栏、可折叠且可调整宽度的分区侧边栏、位于右栏的可折叠页面大纲，以及站点页脚。同一套结构适用于英文、中文和从右向左书写的语言。

导航栏由 Hugo 的 main 菜单与 OINK 自动生成的控件组成：版本选择器、语言选择器、颜色模式控件、搜索，以及项目仓库链接。它会在所有布局上渲染——落地页、文档、博客、Swagger 和分类页面都不例外，因此站点级导航在任何位置都只有一次点击的距离。

navbar_enabled 默认为 true。可以对整个站点关闭导航栏，也可以通过 front matter（前置元数据）cascade 对某个分区关闭，或只对单个页面关闭：

params:
  ui:
    navbar_enabled: false

YAML

---
title: 独立报告
navbar_enabled: false
---

Front matter 的优先级高于站点参数，而且显式写出的 false 在任何层级都会生效。关闭导航栏后，OINK 会恢复此前被导航栏取代的界面：移动端子导航、侧边栏的品牌与搜索行、目录轨道上的工具按钮，以及侧边栏底部的工具区。这个开关适用于必须独占整个视口的页面，不应当作常规排版偏好使用。

导航栏只有两种状态：

宽度	状态
`lg` 及以上	完整：品牌、菜单文字标签与各个工具控件
小于 `lg`	紧凑：先是 Logo，其余条目全部右对齐为图标

紧凑状态并不是精简过的菜单。菜单项保留各自的图标，搜索仍是放大镜，版本、语言与主题控件也停在原处——没有任何东西会折叠进汉堡按钮，因为根本不存在独立的移动菜单。唯一按宽度切换的控件出现在带侧边栏的页面上：小于 md 时会多出一个图标，用于打开侧边栏抽屉。

站点配置

Mon, 01 Jan 0001 00:00:00 +0000

站点跑起来之后，这一章处理站点级的结构性配置：读者怎么导航、内容有几种语言、文档有几个版本、页面操作指向哪个仓库。

具体页面的写法见创作内容，可用组件见组件参考。

本章内容

配置总览：hugo.yaml 的完整参数面
导航与菜单：顶部菜单、侧栏、面包屑
多语言：语言路由、译文回退、RTL
版本管理：多版本文档与版本切换
仓库链接：编辑、历史、报告问题等页面操作的来源

多语言

Mon, 01 Jan 0001 00:00:00 +0000

OINK 直接使用 Hugo 的多语言页面模型，不引入站点专属的域名约定或模板假设。本站以英文为首要语言、简体中文（zh）为第二语言。

配置语言

defaultContentLanguage: en

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    title: Product Documentation
    params:
      description: Product guides and reference
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    title: 产品文档
    params:
      description: 产品指南与参考资料
      time_format_default: 2006年1月2日
      time_format_blog: 2006年1月2日

label , string , required: 语言选择器里显示的名字，用该语言自己的文字写——简体中文 而不是 Chinese。

版本管理

Mon, 01 Jan 0001 00:00:00 +0000

产品有多个受支持版本时，文档通常也要分版本。OINK 提供两样东西：版本切换菜单和归档版本横幅。

各版本具体怎么部署由你决定——常见做法是每个版本一个子域名或子路径，各自独立构建。

在 params.versions 中列出要出现在菜单里的版本：

params:
  version_menu: v2.1
  versions:
    - version: v2.1
      url: https://docs.example.com
    - version: v2.0
      url: https://v2-0.docs.example.com
    - version: v1.9
      url: https://v1-9.docs.example.com

version_menu , string: 菜单按钮上显示的文字，通常是当前版本号。
versions[].version , string , required: 版本标识，显示在菜单项上。
versions[].url , string , required: 该版本文档站的地址。留空的条目会显示为不可用。
version_menu_pagelinks , boolean , default: false: 是否把当前页面路径附加到目标版本的 URL 后面。

菜单里可以用 - name: '---' 插入分隔线，把「受支持版本」和「历史版本」分开：

params:
  versions:
    - name: '**当前版本**'
    - version: v2.1
      url: https://docs.example.com
    - name: '---'
    - name: '**历史版本**'
    - version: v1.9
      url: https://v1-9.docs.example.com

逐页跳转的取舍

version_menu_pagelinks: true 会把当前页面路径拼到目标版本的 URL 上，读者切换版本时停留在同一篇文档。

代码仓库链接与页面信息

Mon, 01 Jan 0001 00:00:00 +0000

OINK 的文档与博客布局可以显示指向当前页面源码仓库的链接。它们位于面包屑行末尾的页面操作菜单中：

查阅 Markdown 源码：当启用 Markdown 输出时，打开生成的 Markdown 备用版本。
查阅编辑历史：打开源文件的提交历史。
编辑本页：打开可编辑的源码视图。
创建子页面：在当前页面下新建文件，并可使用站点的 assets/stubs/new-page-template.md 模板。
创建文档 issue：携带页面上下文，在文档仓库中创建 issue。
创建项目 issue：可选地把 issue 提交到另一个产品仓库。

内置 URL 模式面向 GitHub 风格的代码仓库。如果使用其他兼容托管服务，请逐项验证；如果 URL 结构不同，应覆盖相应 partial。

链接配置

典型站点配置如下：

YAML

params:
  github_repo: https://github.com/OWNER/DOCS
  github_project_repo: https://github.com/OWNER/PRODUCT
  github_branch: main
  github_subdir: site

当内容来自多个代码仓库时，可以在全局、单种语言、分区 cascade 或页面 front matter 中设置这些值。

`github_repo`

文档源码仓库 URL。它用于生成编辑、历史、创建子页面和创建文档 issue 链接：

YAML

params:
  github_repo: https://github.com/pgsty/oink

省略后将隐藏从仓库派生的页面操作。如果页面源码实际位于消费站点，不要把它错误地指向主题仓库。

配置 on OINK

配置

配置原则

完整基线配置

导航与菜单

站点导航栏

关闭导航栏

两种状态，没有独立的移动菜单

站点配置

本章内容

多语言

配置语言

版本管理

版本切换菜单

逐页跳转的取舍

代码仓库链接与页面信息

链接配置

github_repo

`github_repo`