 |
摘要 | DiscoTOC 允许您一键为主题生成交互式目录！ |
 |
预览 | 在 Discourse 主题创建器上预览 |
 |
仓库链接 | https://github.com/discourse/DiscoTOC |
 |
Discourse 主题新手？ | Discourse 主题使用入门指南 |
安装此主题组件
示例
桌面端
移动端
功能
toc = table of contents（目录）
-
通过编辑器齿轮菜单中的按钮自动生成整个目录
-
目录将始终显示在屏幕上 - 随内容滚动，类似于主题进度小部件
-
当您滚动经过主题中的各个部分时，目录中的活动元素将被设置为活动状态（蓝色高亮）
-
每个目录条目都链接到标题的锚点，因此您也可以从其他主题或帖子链接到特定部分
-
点击目录中的任何链接都会指示浏览器导航到相关部分（平滑滚动）
-
在有回复的主题中，目录 / 时间线 按钮让读者在目录和普通主题时间线之间切换。该选择会在浏览器中记住
-
与 Discourse Docs 插件兼容
-
可选支持回复中的目录，而不仅仅是第一帖
-
RTL 支持
它是如何工作的？
简而言之，它查找标记为具有目录的主题中的标题（通过编辑器按钮），如果当前主题被标记，则它会获取所有标题并将它们放入目录中（按标题级别嵌套） - 这意味着您的 Markdown 必须在语法上正确。
# 标题 1
## 标题 2
### 标题 3
#### 标题 4
##### 标题 5
您可以自由地在标题级别之间来回切换，但顺序必须正确
# 标题 2
## 标题 3
## 标题 3
### 标题 4
## 标题 3
# 标题 2
等等...
关于哪些标题兼容的一些须知
- 包含
h1到h5。h6不包含 - 引用内的标题会被忽略，因此引用不会污染目录
- 仅当帖子中的标题数量至少达到 TOC min heading 设置（默认为 3）时，目录才会出现
目录中的链接是如何工作的？
已渲染帖子中的每个标题都会获得一个形式的锚点 p-<post id>-<heading slug>-<number> — 这是标题背后的目标。DiscoTOC 链接到这些锚点，而不是发明自己的锚点。
因为这些锚点包含标题在帖子中的位置，所以如果您重新排序或重命名标题，它们会发生变化。如果您从其他地方链接到各个部分，您可以在标题上方添加稳定的命名锚点：
<div><a name="my-section"></a></div>
## 我的部分
然后链接到 /t/your-topic-slug/1234#my-section。Discourse 允许在帖子中使用 <a name="...">。DiscoTOC 自己的条目仍将使用核心标题锚点，但您的锚点无论编辑如何都会继续工作。
设置
| 名称 | 描述 |
|---|---|
| minimum trust level to create TOC | 在编辑器中看到目录按钮所需的最小信任级别 |
| composer toc text | 出现在编辑器顶部，指示主题将有目录的文本 |
| auto TOC categories | 自动启用目录的分类 |
| auto TOC tags | 自动在带有这些标签的主题上启用目录 |
| enable TOC for replies | 允许回复中的目录。回复中的目录不受 auto TOC tags 和 auto TOC categories 设置的影响，必须手动插入 |
| TOC min heading | 显示目录所需的最小标题数量 |
composer toc text 是出现在编辑器预览中的内容，用于指示将生成目录：
翻译
| 翻译 | 默认值 |
|---|---|
| table_of_contents | table of contents |
| insert_table_of_contents | Insert table of contents |
| jump_bottom | Jump to end |
| toggle_toc.show_timeline | Timeline |
| toggle_toc.show_toc | Contents |
table_of_contents: "table of contents"
这用于移动设备上打开目录的按钮
insert_table_of_contents: "Insert table of contents"
这用作编辑器齿轮菜单中目录按钮的文本
toggle_toc.show_toc: "Contents"
toggle_toc.show_timeline: "Timeline"
这些标签用于在目录和主题时间线之间切换的按钮
我如何创建目录？
- 编写具有语法正确标题的主题
- 点击编辑器齿轮菜单中的目录按钮。默认情况下，它仅出现在主题的第一帖中；启用 enable TOC for replies 设置以在回复中也使用它
- 获利。
当主题有目录时，主题进度小部件会发生什么？
没有空间同时显示两者，因此在有目录的主题中，当您在第一帖时，主题进度小部件被隐藏，您看到的是目录。一旦您滚动过第一帖，目录将被常规的主题进度小部件替换，当您阅读回复时。（如果启用了 enable TOC for replies，拥有自己目录的回复将显示该目录。）
在有多于一帖的主题中，目录 / 时间线 按钮让读者在两者之间切换，并且偏好会在他们的浏览器中记住。
在窄屏幕上，目录通过主题进度区域中的按钮作为覆盖层打开。
使用此组件有任何缺点吗？
几乎所有事情都在客户端发生，因此您可以随时删除组件，您的帖子将像以前一样渲染。唯一触及您内容的是编辑器按钮：它将帖子包装在 <div data-theme-toc="true"> 标记中，这是组件知道帖子应该有目录的方式。如果您卸载组件，该包装器会留在帖子中，但没有可见效果。
局限性
h6 标题和引用内的标题不包含在目录中。
致谢
这最初是 Greg Franko 的 tocify.js 库的硬分叉，此后已重写为原生 Ember 组件。没有外部依赖或请求。
非常感谢 @erlend_sh 提供的大量宝贵反馈，以及 @david 在翻译方面的帮助。