分类: 定制站点

HTML 页面里有侧栏、脚本与样式，模型读它要先剥掉这层外壳。OINK 让同一份内容再产出一份纯 Markdown：每页一个 .md，站点根目录一份 llms.txt 索引，页面上一个「复制 Markdown 文本」按钮。三者都是构建期产物，没有运行时服务，也不需要内容协商。 这三件事都要站点自己在 outputs 里声明，主题不替站点打开。 每页一份 .md markdown 是 Hugo 的内置输出格式。把它加进需要的页面类型： hugo.yml outputs: home: [HTML, …

单页打印不需要配置：外壳（侧栏、目录、顶栏、按钮）都带 d-print-none，浏览器的 Cmd/Ctrl+P 得到的是一份干净的正文。主题因此没有页面级的「打印本页」按钮。 需要配置的是另一件事：把一整个栏目（或一整本书）连同全部子页面合成一份带目录的连续文档。以下内容覆盖启用方式、打印视图的结构，以及排除页面的做法。 启用整章打印 print 是主题声明的自定义输出格式，主题不替站点打开它。在站点自己的 hugo.yml 里给 section 加上： hugo.yml outputs: …

面包屑行右侧的 操作菜单 里与仓库有关的条目，由几个 github_* 参数推导；页尾的「最后修改」信息行来自 git 历史。前提是内容存放在一个 GitHub 风格的仓库里。 四个键接通全部链接 操作菜单里所有跟仓库有关的条目，都由这几个键推导出来： hugo.yml params: github_repo: https://github.com/pgsty/oink.pgsty.com # 文档源码仓库 github_project_repo: …

目录树只有一条路径，分类体系（taxonomy）给页面加第二条：同一篇 PostgreSQL 备份文档既在「运维」目录下，又能从「备份」标签页找到。启用它只需要 Hugo 的 taxonomies: 配置，术语页、筛选芯片、右栏分类云与顶栏分类面板都由主题自动生成，无需编写模板。 本页带着一个分类：标题下面的「分类: 定制站点」一行，以及右栏目录下面那组带计数的芯片，都不需要在页面上写配置。 启用分类法 分类法由 Hugo 决定，主题不额外提供开关。在 hugo.yml 顶层 写 …

产品有多个受支持版本时，文档通常也要分版本。主题提供两项功能：顶栏的版本切换菜单，与旧版本站点上的归档提示横幅。部署布局由站点决定：主题不做跨版本的单次构建，每个版本是一次独立的 Hugo 构建。 版本切换菜单 在 params.versions 里列出要出现在菜单里的版本。这个列表非空时，顶栏工具区出现一个分支图标的菜单，页脚最底层栏出现同样内容的纯图标向上菜单。 hugo.yml params: # 当前站点是哪个版本 version: v2.1 # 菜单的无障碍名称；底栏触发器仍只显示图标 …

OINK 使用 Hugo 的多语言模型，不额外引入目录约定：配置一个 languages 块，译文与原文并排放在同一个目录里，用文件名后缀区分。以下内容覆盖单语言站点扩展为双语站点需要改动的位置，以及双语站点的两处易错点：资源归属与标题锚点。 启用第二种语言 hugo.yml defaultContentLanguage: en languages: en: label: English locale: en-US weight: 1 title: OINK params: …

OINK 的交互式页面自带一套单键快捷键：WASD 在侧栏树中移动，J K 在标题间跳转，Q E 翻页，另有几个单键切换主题、语言与命令面板。默认开启，所有绑定都给输入让行，可以按站点或按页面关闭。 键盘导航不维护第二套状态：树的展开折叠复用侧栏原有的箭头按钮，逐节跳转读取右栏目录，切换语言与主题复用命令面板的同一批动作。键盘操作的顺序与鼠标操作的顺序因此一致。 侧栏 按键 行为 W S ↑ ↓ 焦点移到上一个 / 下一个可见项 A D ← → 折叠 / 展开分组；叶子节点上 A 跳到父级，D …

命令面板是站点唯一的模态入口：搜索页面、复制本页 Markdown、切换语言、切换版本、跳转到站点自定义链接，都在这一个对话框里完成。它随本地搜索一起装配：params.offline_search 关闭时，面板连同索引与 Lunr 都不进入页面，见全文检索。 打开面板 打开方式 打开成什么 点顶栏或侧栏的搜索框 完整搜索态 ⌘ / Ctrl + K 完整搜索态；再按一次关闭 / 完整搜索态 反斜杠键 纯命令态（等于预填了 >） f / c 同上两者，由键盘导航提供 在框里输入 > 开头的查询 …

OINK 的搜索是本地搜索：Hugo 在构建时给每种语言生成一份 JSON 索引，读者的浏览器下载它，在本地完成检索。不需要爬虫、账号、CDN，也不需要联网。主题默认不启用，一行配置即可开启。 搜索的入口是命令面板，打开方式与面板的其余内容见命令面板。 打开本地搜索 hugo.yml params: offline_search: true 这一个键决定索引、Lunr 运行时与搜索对话框是否进入页面。三个条件同时成立时页面才带上它们： params.offline_search 为真； 页面是首 …

本栏目覆盖站点级配置：hugo.yml 里的参数、data/ 下的数据文件、assets/ 下的样式入口。单个页面的写法与 front matter 见创作内容。 按改动目标查找 改动目标 对应页面 站名、Logo、favicon 品牌外观 配色、深浅色模式、字体 品牌外观 顶栏菜单与下拉 导航与菜单 侧栏宽度、图标密度、目录深度 布局与页面类型 首页与落地页 首页与落地页 全文检索与索引范围 全文检索 命令面板里的条目 命令面板 快捷键 键盘导航 新增一门语言 多语言 多版本站点与归档横幅 多 …

本页覆盖页面骨架：有没有侧栏、侧栏多宽、目录收几级、栏目首页是列表还是卡片。内容放在哪个目录见组织内容，这里只讲外壳。 规则是 外壳看 type，不看路径。文档可以放在 content/ 下的任何位置，只要给它 type: docs。 外壳类型 params.ui.shell_types 列出哪些 type 使用带侧栏的阅读外壳： hugo.yml params: ui: shell_types: [docs, book, blog, swagger] type 外壳 docs 文档外壳：左侧栏 …

本页覆盖读者在页面之间移动的入口：顶栏菜单、栏目切换器、面包屑、页面操作、上一页 / 下一页与页脚。侧栏树与目录属于布局与页面类型。 导航没有第二套信息架构：顶栏来自 Hugo 的 menus.main，侧栏来自 content/ 的目录结构。主题不读 docs.json、navigation.yaml 一类的并行导航树。 顶栏菜单 顶层入口写在各语言的 menus.main 里： hugo.yml languages: zh: menus: main: - identifier: docs …

首页不是模板，是一份数据：data/home/<语言>.yaml 里的 sections 列表决定页面从上到下有哪些分区，每个分区的内容在同一份文件里按名字取。普通页面加 layout: landing 也能用同一套分区。 分区全部在服务端渲染。价格、star 数、截图、头像、下载状态都必须在 Hugo 启动前就存在于仓库中，没有分区会在浏览器里取数据。 从 Docsy 的 blocks/* 首页迁移过来的站点要重写首页：主题没有 …

本页覆盖站点外观：站名与 Logo 写在 hugo.yml，配色与字体走 SCSS 入口，页宽与页脚形态是参数。前提是站点已能构建（十分钟上手）。 需要改动的文件有四个：hugo.yml、static/ 下的图标、assets/scss/_variables_project.scss、assets/scss/_styles_project.scss。不要改主题目录里的文件：主题是 Hugo Module，升级时整个目录会被替换。 站名 站名出现在顶栏、浏览器标题与页脚。多语言站每种语言各写一个： …

站点参数的唯一归属页。主题读取的每个键在下面某张表里有一行，给出类型、默认值与一句说明，并链接到讲它的指南页。指南页只给可粘贴的片段，不重复定义。页面级参数（front matter）见页面参数。 表格按功能分组，每组一个 ##，锚点可以引用，例如 /zh/docs/customize/config/#sidebar。默认值一栏空着表示主题没有默认值：不配置该功能就不生效。 hugo.yml 的分层 OINK 站点配置有四类键，改哪一层取决于改动目标： 层 例子 谁定义的 Hugo 原生顶层键 …