配置

使用 Hugo 设置与职责明确的主题参数配置 Oink。
分类:

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

配置原则

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

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。

语言

defaultContentLanguage 决定不带路径前缀的首要站点；语言 weight 控制显示顺序；label 是该语言的自称；locale 提供完整的 HTML 与 SEO locale。对于 RTL 语言，还应设置 languageDirection: rtl。

文件命名

本站使用并置模型：

TEXT 
content/docs/guide.md
content/docs/guide.zh.md

基本名称相同的文件互为译文，其逻辑页面身份应保持一致。OINK 读取 Hugo 建立的翻译关系，不会根据任意 URL 模式猜测。

选择器状态

语言选择器不需要模式参数。只配置一种语言时隐藏；配置两种或更多语言时，点击语言图标会按 weight 顺序切换到下一种语言，悬停半秒或聚焦图标则打开完整菜单。

当前页面缺少目标译文时，会进入目标语言首页。不要为了让选择器停留在同一路径而生成貌似存在、实际失效的页面 URL。

品牌与代码仓库

请设置站点与各语言的 title 和描述。params.logo 可以指向 Hugo Asset，也可以指向 static/ 下的路径。favicon 与社交分享图应放在文档指定的资源位置。

仓库元数据用于生成“编辑此页”、问题反馈和最后修改记录链接：

YAML 
params:
  github_repo: https://github.com/example/product-docs
  github_project_repo: https://github.com/example/product
  github_branch: main
  github_subdir: site

在支持的位置，github_project_repo 默认回退到 github_repo。github_subdir 是内容站在 monorepo 中的路径。github_branch 必须能够解析；用于展示的版本号不一定是 Git ref。

如果希望导航栏、侧边栏抽屉与页脚使用横向品牌图，请设置 params.wordmark。它接受与 params.logo 相同的 Hugo Asset 或 static/ 路径。紧凑状态的导航栏会自动回退到 params.logo，因为横向品牌图会占满整行；完全没有设置 wordmark 时，OINK 保留原有的“图标 + 标题”样式：

YAML 
params:
  logo: images/product-mark.svg
  wordmark: images/product-wordmark.svg

OINK 沿用 Docsy 菜单与 UI 参数，并增加职责明确的外壳控制项：

YAML 
params:
  page_width: normal
  ui:
    navbar_enabled: true
    footer_style: fat # fat | slim | none
    quick_links: [docs, blog]
    sidebar_width_min: 220
    sidebar_width_max: 480
    sidebar_item_overflow: wrap
    sidebar_menu_compact: true
    sidebar_menu_foldable: true
    sidebar_root_enabled: true
    sidebar_root_menu: true
    sidebar_search_disable: false
    breadcrumb_disable: false
    showLightDarkModeMenu: true
    taxonomy_icons:
      categories: fa-solid fa-folder
      tags: fa-solid fa-tags
    page_context_menu:
      enable: true
      assistant_links: false
      links: []
    readingtime:
      enable: true

navbar_enabled 与 footer_style 决定每个页面是否带站点导航栏、以及使用哪种页脚形态。两者默认开启（分别为 true 与 fat），作用于所有布局，可以通过 cascade 按分区覆盖，也可以在页面 front matter 中覆盖；footer_style 取值无法识别时构建会失败。详见导航与菜单与站点页脚。

page_width 接受 normal、wide 或 full，也可以在页面 front matter 中覆盖。侧栏最小与最大值以像素为单位，用来限制桌面端拖动调整的范围。sidebar_item_overflow: wrap 会让长标签换行；其他值保持紧凑的省略号行为。

quick_links 指定外壳中显示的顶层 page reference。请在各语言主菜单中定义相应的本地化名称。taxonomy_icons 按分类复数名设置右栏分组图标，默认 categories 用文件夹、tags 用标签，其余分类使用通用形状图标。

页面操作是面包屑行中的拆分按钮：左半边复制本页 Markdown，菜单则在所有视口宽度下保证「复制 Markdown 文本」、助手入口、「查阅 Markdown 源码」「查阅编辑历史」「编辑本页」「创建子页面」、文档与项目 issue，以及「打印整个分区」都可访问。内置 ChatGPT 和 Claude 助手入口默认关闭；设置 assistant_links: true 后才会在有源文件的页面上显示。读者激活入口时，完整的当前 URL（包括 query string 与 fragment）会随本地化提示词离开本站；OINK 不会上传页面正文。请勿在 URL 中放置秘密信息，并披露这一第三方边界。页面可用布尔型 assistant_links front matter 覆盖站点策略。

当 github_repo 能解析“编辑此页面”使用的同一仓库路径时，才会显示“查阅编辑历史”。links 默认为空，额外的自定义链接可使用经过 URL 编码的 {url}、{title} 与 {markdown_url} 占位符：

YAML 
params:
  ui:
    page_context_menu:
      enable: true
      assistant_links: true
      links: []
      # - name: 询问外部助手
      #   icon: fa-solid fa-wand-magic-sparkles
      #   url: https://assistant.example/new?source={markdown_url}&title={title}

首页内容位于 data/home/<language>.yaml；缺少相应语言数据时回退到英文。每个语言文件包含具名数据块，以及一个可选的 sections 列表；该列表会按照准确顺序把数据块组合成首页。页脚已不再属于这份文件——它现在渲染在所有布局上，数据读取自 data/footer/<language>.yaml。详见站点页脚。

组合首页分区

字符串条目会同时把该值用作分区类型与数据键。映射条目可以选择内置 type，读取另一个具名 key，设置稳定 id，或临时设置 enabled: false：

YAML 
sections:
  - hero
  - metrics
  - capabilities
  - type: logo-wall
    key: ecosystem
  - gallery
  - faq
  - cta

ecosystem:
  title: 使用熟悉的工具构建
  columns: 4
  items:
    - {
        name: Hugo,
        icon: fa-solid fa-bolt,
        url: https://gohugo.io/,
        external: true,
      }

映射条目也可以通过 data 直接携带内容，适合短小且只使用一次的区块。两个分区需要相同呈现时，可以用不同的键重用内置类型。站点自有布局还可以指定 partial，但这属于自定义模板契约，而不是可移植的首页数据。

如果没有 sections，OINK 会保留 0.1.x 的顺序，从 hero、metrics、capabilities、principles 与 cta 中按存在情况进行渲染。添加 sections 表示显式组合；此后即使文件中仍有某个数据块，只要列表没有引用，它就不会出现在首页。

内置分区

OINK 0.4.0 提供 21 种分区类型：

类型 适用内容
hero 核心信息、操作按钮与跟随主题的图片
metrics 紧凑的事实、数字、链接与辅助文字
capabilities 交替的功能叙事与专用视觉面板
principles 带编号的产品原则或工作原则
cards 通用功能、价值、服务或路径集合
logo-wall 工具、集成、合作伙伴或项目渊源
gallery 带徽标与操作的截图或图标示例
testimonials 带可选署名与来源链接的引语
contributors 人员、角色、头像与个人页链接
faq 使用原生展开控件与 Markdown 答案的问答
markdown 没有合适集合布局时使用的自由文字
cta 最后一个操作，或一组紧凑操作
pricing 产品层级、价格、功能与操作按钮
pricing-compare 不同价格层级之间的功能对比矩阵
command-box 带复制操作与可选说明的聚焦命令
steps 带可选命令示例的有序步骤
timeline 带日期的里程碑、路线图与发布历史
code-plate 展示面板中的静态代码或逐行内容
case-study 带指标、引语和来源的证据型案例
download 经过验证的滚动与固定版本下载渠道
bar-chart 无需图表 JS 的非负数值比较

首页与普通 layout: landing 页面使用同一套注册表。数据解析、9 种场景型分区契约、无 JavaScript 行为与输出规则见 Landing 页面。

通用集合区块接受 eyebrow、title、desc 或 text、 columns 与 items。条目字段随呈现方式而异，但统一使用 title 或 name、desc 或 text、icon、image、url 与 external。普通文字字段会渲染 Markdown。站内 URL 应相对于当前语言根路径；应作为外部导航打开的链接设置 external: true。

每个区块都可以省略，因此无需复制布局也能得到更精简的首页。例如：

YAML 
hero:
  eyebrow: 本地优先的产品文档
  title_lines:
    - words:
        - { mark: P, text: roduct, color: red }
        - { mark: D, text: ocs, color: blue }
  lead: 只用 Hugo 构建和交付的技术文档。
  image:
    light: images/hero-light.webp
    dark: images/hero-dark.webp
    alt: 产品文档工作流插图
  actions:
    - { label: 阅读文档, url: docs/, icon: fa-solid fa-book, style: primary }

可选的 hero.image 会在 Hero 右侧添加一幅跟随颜色主题的图片。将 light 与 dark 指向站点 static/ 目录下的文件，图片会随主题选择器切换。只配置 src、light 或 dark 中的一项时，OINK 会在两种主题下复用该图；也可以直接用字符串配置通用图片。省略 image 则保持纯文字 Hero。

首页各分区之下，每个页面都以同一个站点页脚收尾：footer_style 为 fat 时先渲染多列网格，然后是 bottom bar。左侧保留 Docsy 的 params.copyright API：可以使用 Markdown 字符串，也可以使用包含 authors、from_year、to_year 的 Map；未设置时原样渲染 Hugo 顶层的 copyright。OINK 的 params.footer_center_info 接受行内 Markdown，默认显示 Powered by Oink，显式设为空字符串可隐藏中间区域。右侧保留语言控件。

仍在 data/home/<language>.yaml 中保留 footer 块的站点照常读取该数据。这份数据现在供给所有页面的页脚，而不只是首页。方便时请迁移到 data/footer/<language>.yaml。

可导航的功能面板

价值主张区块可以把组件面板变成紧凑导航。为每个可导航项目添加 url，用 aria_label 命名导航区域，并配置一至四列。没有 URL 的项目仍是装饰卡片，因此既有面板会保持原有行为：

YAML 
capabilities:
  items:
    - title: 按需加载内容能力
      visual:
        type: components
        aria_label: 浏览内容组件
        columns: 3
        compact: true
        items:
          - {
              title: Asciinema,
              icon: fa-solid fa-terminal,
              url: docs/components/layout/#asciinema,
            }
          - {
              title: Mermaid,
              icon: fa-solid fa-share-nodes,
              url: docs/components/diagrams/#diagrams-with-mermaid,
            }

项目站默认启用本地搜索：

YAML 
params:
  offlineSearch: true
  offlineSearchIndex: summary
  offlineSearchSummaryLength: 70
  offlineSearchMaxResults: 10

offlineSearchIndex 控制每种语言索引中可下载的文本范围，四档范围逐级累加：title 索引标题与分类元数据；heading 增加页面标题；summary 增加描述或摘要；content 再加入完整正文。content 是兼容旧行为的默认值，而多数文档站可从体积更小的 summary 开始。offlineSearchMaxResults 同时约束 Lunr 与 CJK 子串兜底结果数。

每种语言都会得到独立索引。通过 Docsy 既有配置仍可使用托管搜索，但启用它们会显式增加外部服务边界。除非已经决定界面应显示哪一种，否则不要同时配置多个相互竞争的搜索提供方。

内容运行时

纯浏览器运行时

Mermaid 与 KaTeX 会根据内容自动检测；Markmap 需要在站点级启用：

YAML 
params:
  markmap:
    enable: true
  mermaid:
    theme: default

Swagger UI、Redoc、Asciinema、ECharts、Infographic 与轮播资源会在相应短代码出现时加载。它们的本地运行时路径属于内部实现，不应配置。

服务端点

PlantUML 与 Diagrams.net 需要显式端点：

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

网络隔离站点应保持这些功能关闭，除非上述 URL 可以在隔离网络内部访问。

页面级覆盖

Hugo 的 .Param 查找机制允许在 front matter 中覆盖许多站点参数：

YAML 
---
title: Wide reference
page_width: wide
navbar_enabled: false
footer_style: slim
hide_feedback: true
hide_readingtime: true
ui:
  no_left_sidebar: false
  scrollSpy:
    disable: false
---

navbar_enabled 与 footer_style 直接从 front matter 顶层读取，不在 ui 块内，因此分区可以在自己的 cascade 中一次性设定。

只应为真实的内容差异使用覆盖，不要靠逐页设置重建另一套视觉系统。

避免虚假配置

不要暴露：

  • 在“Docsy”与“OINK”外壳之间切换的开关；
  • vendor JavaScript、CSS、字体或内部 partial 的路径；
  • 品牌命名空间下重复的语言或仓库值；
  • 只用于二选一复制实现的开关。

如果站点需要定制产品矩阵或门户，请把该组件留在站点，并使用范围明确的 hook 或短代码。清晰的本地业务功能，优于误导性的全局主题选项。

验证配置变更

修改配置后：

  1. 分别使用最低支持版本与当前验证版本的 Hugo Extended 构建；
  2. 测试每种已配置语言，以及至少一个缺少译文的页面；
  3. 如果同时支持根路径与子路径部署，验证两种 baseURL 输出；
  4. 检查本地搜索与可选运行时请求；
  5. 检查桌面端和移动端外壳、深浅色主题与打印输出。

真正可接受的配置必须能够正确构建并按预期运行，而不只是可以被 YAML 解析。

最后修改 2026年8月14日 · chore: update site to OINK v0.4.1 (911d6a9)