配置

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

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

配置原则

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

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

完整基线配置

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

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
  footer_icp: ''
  footer_icp_url: https://beian.miit.gov.cn/
  copyright:
    authors: Example Authors
    from_year: 2026
  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。

文件命名

本站使用并置模型：

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

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

选择器状态

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

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

品牌与代码仓库

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

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

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/ 路径。省略 wordmark 时，OINK 保留原有的“图标 + 标题”样式：

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

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

params:
  page_width: normal
  ui:
    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
    page_context_menu:
      enable: true
      links: []
    readingtime:
      enable: true

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

quick_links 指定外壳中显示的顶层 page reference。请在各语言主菜单中定义相应的本地化名称。

页面上下文菜单在所有视口宽度下都把“复制 Markdown”“查看 Markdown”、编辑、反馈与打印入口放在页面标题旁。links 默认为空，因此站点未主动启用时，不会向外部 AI 服务发送页面信息。自定义链接可使用经过 URL 编码的 {url}、{title} 与 {markdown_url} 占位符：

params:
  ui:
    page_context_menu:
      enable: 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 列表；该列表会按照准确顺序把数据块组合成首页。页脚使用同一份文件，但不受 sections 控制。

组合首页分区

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

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.2.0 提供 12 种分区类型：

类型	适用内容
`hero`	核心信息、操作按钮与跟随主题的图片
`metrics`	紧凑的事实、数字、链接与辅助文字
`capabilities`	交替的功能叙事与专用视觉面板
`principles`	带编号的产品原则或工作原则
`cards`	通用功能、价值、服务或路径集合
`logo_wall`	工具、集成、合作伙伴或项目渊源
`gallery`	带徽标与操作的截图或图标示例
`testimonials`	带可选署名与来源链接的引语
`contributors`	人员、角色、头像与个人页链接
`faq`	使用原生展开控件与 Markdown 答案的问答
`markdown`	没有合适集合布局时使用的自由文字
`cta`	最后一个操作，或一组紧凑操作

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

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

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 }

footer:
  brand:
    name: Product Docs
    tagline: 支持 **Markdown** 的简短介绍。
    slogan: 让答案离产品更近。
  columns:
    - title: 产品
      links:
        - { label: 概览, url: docs/ }

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

首页会在通用小页脚上方渲染品牌与导航组成的大页脚。小页脚左侧来自 params.copyright，中间使用可选的 params.footer_icp 与 params.footer_icp_url，右侧列出所有已配置语言。版权作者与大页脚品牌文字中的 Markdown 会渲染为真实链接与行内标记。

可导航的功能面板

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

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

搜索

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

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

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

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

内容运行时

纯浏览器运行时

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

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

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

服务端点

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

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 中覆盖许多站点参数：

---
title: Wide reference
page_width: wide
hide_feedback: true
hide_readingtime: true
ui:
  no_left_sidebar: false
  scrollSpy:
    disable: false
---

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

避免虚假配置

不要暴露：

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

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

验证配置变更

修改配置后：

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

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

JavaScript is required to load comments. View discussions on GitHub.

配置