定制站点 on OINK

配置总览

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

站点参数的唯一归属页。主题读取的每个键在下面某张表里有一行，给出类型、默认值与一句说明，并链接到讲它的指南页。指南页只给可粘贴的片段，不重复定义。页面级参数（front matter）见页面参数。

品牌外观

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

本页覆盖站点外观：站名与 Logo 写在 hugo.yml，配色与字体走 SCSS 入口，页宽与页脚形态是参数。前提是站点已能构建（十分钟上手）。

需要改动的文件有四个：hugo.yml、static/ 下的图标、assets/scss/_variables_project.scss、assets/scss/_styles_project.scss。不要改主题目录里的文件：主题是 Hugo Module，升级时整个目录会被替换。

首页与落地页

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

首页不是模板，是一份数据：data/home/<语言>.yaml 里的 sections 列表决定页面从上到下有哪些分区，每个分区的内容在同一份文件里按名字取。普通页面加 layout: landing 也能用同一套分区。

导航与菜单

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

本页覆盖读者在页面之间移动的入口：顶栏菜单、栏目切换器、面包屑、页面操作、上一页 / 下一页与页脚。侧栏树与目录属于布局与页面类型。

导航没有第二套信息架构：顶栏来自 Hugo 的 menus.main，侧栏来自 content/ 的目录结构。主题不读 docs.json、navigation.yaml 一类的并行导航树。

布局与页面类型

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

本页覆盖页面骨架：有没有侧栏、侧栏多宽、目录收几级、栏目首页是列表还是卡片。内容放在哪个目录见组织内容，这里只讲外壳。

规则是 外壳看 type，不看路径。文档可以放在 content/ 下的任何位置，只要给它 type: docs。

定制站点

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

本栏目覆盖站点级配置：hugo.yml 里的参数、data/ 下的数据文件、assets/ 下的样式入口。单个页面的写法与 front matter 见创作内容。

按改动目标查找

改动目标	对应页面
站名、Logo、favicon	品牌外观
配色、深浅色模式、字体	品牌外观
顶栏菜单与下拉	导航与菜单
侧栏宽度、图标密度、目录深度	布局与页面类型
首页与落地页	首页与落地页
全文检索与索引范围	全文检索
命令面板里的条目	命令面板
快捷键	键盘导航
新增一门语言	多语言
多版本站点与归档横幅	多版本
标签与分类	分类体系
编辑本页、最后修改、贡献者	仓库与页面信息
打印与整章导出	打印支持
`llms.txt` 与每页 `.md` 输出	Agent 支持
某个参数的类型与默认值	配置总览

评论、分析与部署需要接入外部服务，见维护管理。

全文检索

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

OINK 的搜索是本地搜索：Hugo 在构建时给每种语言生成一份 JSON 索引，读者的浏览器下载它，在本地完成检索。不需要爬虫、账号、CDN，也不需要联网。主题默认不启用，一行配置即可开启。

命令面板

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

命令面板是站点唯一的模态入口：搜索页面、复制本页 Markdown、切换语言、切换版本、跳转到站点自定义链接，都在这一个对话框里完成。它随本地搜索一起装配：params.offline_search 关闭时，面板连同索引与 Lunr 都不进入页面，见全文检索。

键盘导航

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

OINK 的交互式页面自带一套单键快捷键：WASD 在侧栏树中移动，J K 在标题间跳转，Q E 翻页，另有几个单键切换主题、语言与命令面板。默认开启，所有绑定都给输入让行，可以按站点或按页面关闭。

多语言

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

OINK 使用 Hugo 的多语言模型，不额外引入目录约定：配置一个 languages 块，译文与原文并排放在同一个目录里，用文件名后缀区分。以下内容覆盖单语言站点扩展为双语站点需要改动的位置，以及双语站点的两处易错点：资源归属与标题锚点。

多版本

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

产品有多个受支持版本时，文档通常也要分版本。主题提供两项功能：顶栏的版本切换菜单，与旧版本站点上的归档提示横幅。部署布局由站点决定：主题不做跨版本的单次构建，每个版本是一次独立的 Hugo 构建。

分类体系

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

目录树只有一条路径，分类体系（taxonomy）给页面加第二条：同一篇 PostgreSQL 备份文档既在「运维」目录下，又能从「备份」标签页找到。启用它只需要 Hugo 的 taxonomies: 配置，术语页、筛选芯片、右栏分类云与顶栏分类面板都由主题自动生成，无需编写模板。

仓库与页面信息

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

面包屑行右侧的 操作菜单 里与仓库有关的条目，由几个 github_* 参数推导；页尾的「最后修改」信息行来自 git 历史。前提是内容存放在一个 GitHub 风格的仓库里。

四个键接通全部链接

操作菜单里所有跟仓库有关的条目，都由这几个键推导出来：

打印支持

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

单页打印不需要配置：外壳（侧栏、目录、顶栏、按钮）都带 d-print-none，浏览器的 Cmd/Ctrl+P 得到的是一份干净的正文。主题因此没有页面级的「打印本页」按钮。

Agent 支持

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

HTML 页面里有侧栏、脚本与样式，模型读它要先剥掉这层外壳。OINK 让同一份内容再产出一份纯 Markdown：每页一个 .md，站点根目录一份 llms.txt 索引，页面上一个「复制 Markdown 文本」按钮。三者都是构建期产物，没有运行时服务，也不需要内容协商。