ghost-toc-plugin 预览

在左侧面板修改选项。目录会实时重新渲染，嵌入代码也随之更新。滚动时会高亮当前所在的章节。

开始之前

ghost-toc-plugin 是一个仅约 3KB、无依赖的浮动目录组件，一行代码即可为 Ghost 博客添加目录。它最初是为 Ghost 而做，但同样适用于基于 Notion 的博客，以及任何能添加脚本的地方。它会读取文章中的标题自动生成目录，随页面滚动并高亮你正在阅读的章节。本页就是实时示例，侧边的目录正是真实运行的组件。

安装方法

无需构建、无需修改主题文件，粘贴下面这段代码即可完成安装：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-toc-plugin@1/toc.css">
<script src="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-toc-plugin@1/toc.min.js"
        data-content=".gh-content"
        data-headings="h2,h3"
        data-title="目录"></script>

代码注入

在 Ghost 中，粘贴到 Settings → Code injection → Site Footer。基于 Notion 的托管，则放进自定义代码处：oopy 在站点设置里有 head/footer 代码框，super.so 有 Custom Code 区域，在那里把 data-content 设为 .notion-page-content。其他网站则放在结束标签 </body> 之前。请勿添加 async 或 defer，以便它读取自身的 data-* 选项。

选项设置

所有行为都通过脚本标签上的 data-* 属性配置: 可设置正文选择器、要包含的标题、标题文字、位置等：

data-content=".gh-content"
data-headings="h2,h3"
data-position="right"
data-min-width="1200"
data-top="100"

自定义

颜色和位置都可以自由调整。所有类名和 CSS 变量都以 greedylabs-ghost-toc 命名空间隔离，绝不会与你的主题冲突。

颜色

当前项的颜色默认跟随 Ghost 主题强调色（--ghost-accent-color）。要更改，可设置 data-accent 或覆盖 CSS 变量。组件内置浅色和深色默认值，会自动适配系统主题。若想提升深色模式下的可读性，请仅针对深色覆盖颜色, 单一固定值会在浅色下显得不协调：

@media (prefers-color-scheme: dark) {
  .greedylabs-ghost-toc {
    --greedylabs-ghost-toc-muted: #c9d1d9;
    --greedylabs-ghost-toc-border: rgba(255,255,255,.22);
  }
}

位置

用 data-position 设置左右，data-top 设置顶部偏移，data-gap 设置与正文的间距，data-width 设置面板宽度。当屏幕窄于 data-min-width，或正文旁没有空间时，目录会自动隐藏。

常见问题

这个小组件会拖慢我的网站吗？

几乎不会。它约 3KB，没有依赖，也不发起外部请求。滚动通过 passive 监听器处理，并用 requestAnimationFrame 合并为每帧只计算一次；只有当文档高度变化时（懒加载图片、giscus 等组件）才通过 ResizeObserver 重新计算。

为什么目录没有显示？

请检查三点：data-content 选择器是否匹配真正的文章容器；标题是否至少有两个（少于两个不会生成目录）；视口是否宽于 data-min-width（默认 1200px）且正文旁边有放置面板的空间。在窄屏和移动端它会故意隐藏。

能把 h4 等更深的标题也加入目录吗？

可以。在 data-headings 中用逗号列出想要的标签（例如 h2,h3,h4）。你可以自由决定目录中显示哪些标题层级。

结语

ghost-toc-plugin 是 MIT 许可的开源项目，代码与问题反馈都在 GitHub 上。在左侧面板调整选项、实时查看预览，满意后复制嵌入代码即可。如果它帮到了你，欢迎请我喝杯咖啡 ☕。