Quartz 5 目录生成插件 TableOfContents 完全指南：从安装配置到源码级原理

Quartz 5 目录生成插件 TableOfContents 完全指南从安装配置到源码级原理【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz导读TableOfContents 是 Quartz 5 中负责从 Markdown 标题自动生成页面目录TOC的社区插件属于Transformer Component双类型插件Transformer 在构建阶段扫描各页面的标题层级生成目录结构Component 则负责在页面布局中渲染目录并高亮当前滚动位置。本文基于仓库中的 docs/plugins/TableOfContents.md 与 docs/features/table of contents.md 编写完整覆盖其全部配置项maxDepth、minEntries、showByDefault、collapseByDefault、layout、安装方式、布局摆放与 TS 覆写 API并结合quartz.config.default.yaml、CLI 插件管理实现等源码细节帮助你在不写一行代码的前提下快速调出符合站点风格的目录同时理解其底层工作方式。一、这个插件做了什么TableOfContents 插件为每个 Markdown 文档生成目录Table of Contents。构建时插件会遍历页面中的所有标题按层级组织成目录树并渲染到页面上。除了静态的目录列表它还会追踪你的滚动位置——当你滚动阅读时已经滚过的标题会以不同的颜色高亮显示帮助你在长文中定位阅读进度。在 Quartz 5 的插件体系中docs/plugins/index.md 明确指出Some plugins span multiple categories.TableOfContentsis both a transformer and a component.这意味着该插件的灵魂分为两部分角色职责阶段Transformer从 Markdown 的#~######标题中提取并生成目录数据结构构建期Component把目录渲染成页面右侧的 UI处理折叠、高亮、现代/传统两种视觉样式渲染期Transformer 负责算出来Component 负责画出来。这也是为什么插件文档中专门有一条警告见下文第四节Component 缺失时目录不会显示。二、默认行为开箱即用的目录根据功能文档 docs/features/table of contents.md插件的默认行为是自动从每页的标题列表生成 TOC默认展示H1# Title到 H3### Title的所有标题只有当页面标题数多于一个时才显示目录单标题页面不显示随滚动高亮已经滚动过的标题目录组件默认显示在页面右侧边栏right sidebar。单页禁用目录如果你希望某个页面不显示目录只需在该页的 frontmatter 中加入--- enableToc: false ---这个 frontmatter 字段与配置项showByDefault配合使用详见第四节实现全局默认显示、个别页面隐藏的常见需求。三、安装插件TableOfContents 是社区插件community plugin独立维护在quartz-community/table-of-contents仓库中需要单独安装。官方安装命令npx quartz plugin add github:quartz-community/table-of-contents该命令会将插件克隆到.quartz/plugins/目录并把插件条目写入quartz.config.yaml版本信息记录在quartz.lock.json中。相关 CLI 细节可参考 docs/cli/plugin.md。如果你在克隆他人项目后需要同步安装配置中声明的所有插件CI 或新机器场景可使用npx quartz plugin install --from-config清理已从配置移除的插件则用npx quartz plugin prune。实际上Quartz 5 的所有项目模板默认已内置并启用了该插件。在 quartz.config.default.yaml 以及quartz/cli/templates/下的default.yaml、blog.yaml、obsidian.yaml、ttrpg.yaml四个模板中都能看到完全一致的默认配置条目- source: quartz-community/table-of-contents enabled: true order: 50 layout: position: right priority: 30enabled: true默认启用order: 50在 transformer 流水线中的执行顺序位于语法高亮 order 20、GFM order 40 之后crawl-linksorder 60 之前layout.position: right目录组件渲染在右侧边栏layout.priority: 30右侧边栏内的排序优先级数字越小越靠上例如 graph 为 10、backlinks 为 50目录居中。也就是说用默认模板创建的新站点无需任何配置即可获得目录功能本插件绝大多数情况下你只需要调整options甚至什么都不用改。四、完整配置选项全部 5 项参数详解插件文档 docs/plugins/TableOfContents.md 给出以下配置项。以下是每一项的含义、取值范围与典型用法配置项说明取值范围默认值maxDepth限制目录中包含的标题深度1表示只含顶级标题6表示包含全部六级标题1~63minEntries页面标题数达到该最小值时才显示目录正整数1showByDefault目录是否默认显示可被页面 frontmatter 覆盖true/falsetruecollapseByDefault目录初始是否处于折叠状态true/falsefalselayout目录组件的视觉布局modern/legacymodern在quartz.config.yaml中为插件添加options块即可配置plugins: - source: quartz-community/table-of-contents enabled: true options: maxDepth: 4 # 目录最深展示到 H4 minEntries: 2 # 页面至少有 2 个标题才显示目录 showByDefault: true # 默认显示 collapseByDefault: false # 默认展开 layout: modern # 现代风格或 legacy 传统风格 order: 50 layout: position: right priority: 30参数实战解读maxDepth控制目录多深。默认3对应功能文档所述的H1 到 H3对技术文档这类长文可调到4甚至5展示子章节对极简博客保持2~3即可避免目录过长。minEntries控制目录多长才出现。默认1意味着标题数 1 即显示与功能文档描述的默认行为一致如果你的文章偏短可以调高到3或5避免短小页面也占用侧边栏空间。showByDefault全局开关。配合 frontmatter 的enableToc: false即可实现默认开、个别页关反过来若全局设为false理论上也可以用 frontmatter 开启——但最常用的还是默认true 单页禁用。collapseByDefault设true时目录初始折叠用户点击后再展开适合目录很长、想给正文让位的场景默认false保持展开。layoutmodern默认与legacy是两种视觉实现。legacy对应 Quartz 早期版本的经典目录样式modern是社区维护的新样式通常带更精致的层级缩进与滚动高亮动效。可按站点整体视觉风格选择。重要警告Transformer 与 Component 必须成对出现插件文档以 warning 形式强调本插件需要quartz.config.yaml中存在Plugin.TableOfContents组件来决定目录显示在哪里。缺少它时什么都显示不出来。两者应当始终一起添加或一起移除。换句话说只安装 transformer生成目录数据而不放置 component渲染目录页面上不会出现任何目录反过来只放组件但没有 transformer 产出数据组件也无内容可渲染。在默认模板中这一对依赖已经由quartz-community/table-of-contents单一条目自动满足其 manifest 同时声明了 transformer 与 component 两种类型因此日常使用无需关心拆分但当你手工从配置中删除/添加条目时务必整体操作不要只删一半。五、目录的摆放位置理解 layout 机制目录组件在页面中的位置由插件的layout块控制。在 Quartz 5 中布局由quartz.config.yaml的顶层layout章节统一管理每个插件通过layout.position与layout.priority声明自己挂载到哪个区域、在该区域内的次序。可用的页面区域定义在 quartz/cfg.ts 的FullPageLayout接口中export interface FullPageLayout { head: QuartzComponent // single component header: QuartzComponent[] // laid out horizontally beforeBody: QuartzComponent[] // laid out vertically pageBody: QuartzComponent // single component afterBody: QuartzComponent[] // laid out vertically left: QuartzComponent[] // vertical on desktop and tablet, horizontal on mobile right: QuartzComponent[] // vertical on desktop, horizontal on tablet and mobile footer: QuartzComponent[] // laid out vertically }目录的默认位置是right右侧边栏桌面端垂直排列、平板与移动端水平排列。若想改成左侧边栏只需修改插件的layout.position- source: quartz-community/table-of-contents enabled: true layout: position: left # 改为左侧边栏 priority: 15完整的布局编排规则groups 分组、byPageType 覆盖、条件渲染等见 docs/layout.md。需要特别注意的是右侧边栏在不同页面类型下可以被裁剪——例如 quartz.config.default.yaml 中layout.byPageType.folder与tag都将right设为[]清空右侧栏这意味着目录在 folder/tag 列表页不会显示这属于预期行为不是插件故障。六、通过 quartz.ts 进行高级覆写如果 YAML 无法满足需求例如需要按页面动态决定是否显示目录、需要自定义排序或过滤逻辑Quartz 支持在 quartz.ts 中用 TypeScript 覆写。社区插件在 TS 覆写中通过ExternalPlugin.X()引用本插件的工厂函数为ExternalPlugin.TableOfContentsTransformer()根据 docs/configuration.md 的说明插件覆写必须放在loadQuartzConfig()之前且 TS 中设置的 options 会与 YAML 合并并优先于 YAMLimport { loadQuartzConfig, loadQuartzLayout } from ./quartz/plugins/loader/config-loader import * as ExternalPlugin from ./.quartz/plugins ExternalPlugin.TableOfContentsTransformer({ maxDepth: 4, minEntries: 2, showByDefault: true, collapseByDefault: false, layout: modern, }) const config await loadQuartzConfig() export default config export const layout await loadQuartzLayout()从源码看插件加载链路从源码结构看ExternalPlugin来自.quartz/plugins该目录由 quartz/plugins/loader/install-plugins.ts 对应的 CLI 流程npx quartz plugin install负责维护——它读取quartz.config.yaml中的source列表、解析并克隆到.quartz/plugins/随后构建索引供quartz.ts导入。而 quartz/plugins/config.ts 中的getPluginInstance/isLoadedPlugin则负责把已加载插件LoadedPlugin按类型transformer / filter / emitter / pageType实例化并送入各自的流水线。可以推断TableOfContentsTransformer()在 config 加载期被实例化为 transformer 实例其生成的目录数据在构建流水线中注入页面最终由同名 component 消费渲染——这也解释了必须成对添加/移除的约束。七、API 速查插件文档 docs/plugins/TableOfContents.md 在末尾给出了标准 API 摘要项目值Category类别Transformer, ComponentFunction name函数名ExternalPlugin.TableOfContentsTransformer()Source来源仓库quartz-community/table-of-contentsInstall安装命令npx quartz plugin add github:quartz-community/table-of-contentsenabled默认启用truerequired非必需false注意enabled: true表示该插件在默认模板中处于启用状态required: false表示它不是 Quartz 运行所必需的——删除它只会失去目录功能不会影响站点构建。八、常见问题与排障1. 安装了插件但页面上没有目录优先检查quartz.config.yaml中该条目的layout.position是否指向了一个实际存在的布局区域以及对应页面类型是否清空了该区域如默认配置中 folder / tag 页的right: []。同时确认 transformer 与 component 成对存在第四节警告。2. 目录太深/太浅调整maxDepth1~6。默认 3 覆盖 H1~H3。3. 短文章也显示目录想隐藏调高minEntries或在具体页面 frontmatter 加enableToc: false。4. 想让目录默认折叠设置collapseByDefault: true。5. 目录样式想回到旧版将layout设为legacy。6. 在 TS 覆写中修改配置不生效确认ExternalPlugin.TableOfContentsTransformer({ ... })写在loadQuartzConfig()之前并重新构建站点。九、延伸阅读功能总览docs/features/table of contents.md插件配置与安装docs/configuration.md布局系统docs/layout.md插件 CLI 管理docs/cli/plugin.md插件分类与多类型说明docs/plugins/index.md默认配置示例quartz.config.default.yaml【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考