定制站点 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

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 文本」按钮。三者都是构建期产物，没有运行时服务，也不需要内容协商。