配置

使用 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。

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；缺少相应语言数据时回退到英文。可配置的顶层区块包括 hero、metrics、capabilities、principles、cta 与 footer。每个区块都可以省略，因此无需复制布局也能得到更精简的首页。例如：

hero:
  eyebrow: 本地优先的产品文档
  title_lines:
    - words:
        - { mark: P, text: roduct, color: red }
        - { mark: D, text: ocs, color: blue }
  lead: 只用 Hugo 构建和交付的技术文档。
  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/ }

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

搜索

starter 默认使用本地搜索：

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 可以在隔离网络内部访问。

ECharts 迁移开关

结构化 ECharts 输入默认安全：

params:
  content:
    echarts_unsafe: false

只有迁移包含 JavaScript 且已经审查的旧页面时，才把它设为 true。更好的做法是在最小范围的短代码实例上设置 unsafe=true，随后重写图表并删除例外。

页面级覆盖

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 解析。

配置