DiscoTOC - 自動内容表格

示例

桌面

移動終端

特性

toc = table of contents（内容清單）

• 通過菜單上面的設定按鈕，根據目前内容的狀況一鍵生成 toc 清單
• Toc 将會一直在頁面中盡顯顯示 —— 滾動内容與 topic 的連結是同步的
• 當你滾動過目前頁面中中的主題的時候，對應這個主題的内容清單将會使用高亮來進行顯示（顯示為綠色）
• 針對标題添加屬性（你可以從其他的 topic / post 中來連結到特定的内容）
• 通過單擊 toc 的主題連結，浏覽器将會導航到正文内容的對應位置上（同步滾動）
• 針對每一個标題添加一個可以拷貝的連結（當然是在你期望的情況下）
• RTL 支援
• 配色方案基于你目前使用的配色方案

是如何進行工作的

在預設情況下，目前的内容的标題将會被标記為 toc（通過 composer 按鈕來完成上面的操作的），同時如果你的目前主題是被标記的話，這個也将會被轉換為 toc（這個與目前标題的層次有關），所有的内容标題都會被轉換為 TOC —— 這就意味着，你的 MD 檔案的标題設定是必須正确的，如果你的标題設定層級有錯誤，那麼轉換的結果也會出錯.。

# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6
           

針對層級，你可以随意進行調整，但是你必須要保證層級的正确。

# heading 2 
## heading 3
## heading 3
### heading 4
## heading 3
# heading 2

etc...
           

為了保證連結能夠正常工作，所有的标題必須要有 Id 屬性。

這個元件将會自動對标題的 Id 進行校驗，如果标題是存在的話，那麼這個元件将能夠更加有效的執行。同時 Id 在你手動建立主題的時候也更加有用。

如果你的标題沒有 Id 的話，這個元件将會根據标題的内容來自動建立 Id（對不需要的字元将會自動的被忽略）。

當上面的所有内容完成後，TOC 将會根據标題建立一個連結到正文的連結，如下圖：

設定

這個元件隻有一個設定，就是 Toc 的圖示（這個圖檔将會在後面的設定中使用，官方不建議對這個圖示進行修改。）

翻譯和本地化

這個元件需要翻譯的内容也非常少，隻有下面 3 個字段需要翻譯。

table_of_contents: "table of contents（内容清單）"
           

這個将會在移動終端上打開 TOC 的時候顯示

insert_table_of_contents: "Insert table of contents（插入内容清單）"
           

這個是在内容清單被插入到主題頁面的時候來進行顯示的。

topic_will_contain_a_table_of_contents: "This topic will contain a table of contents（本内容将會提供主題清單）"
           

這個内容将會在你對主題内容進行編輯的時候，在右側進行預覽的時候顯示在預覽頁面上。This is the text that shows up in the composer preview to indicate that the a toc will be generated for the topic

如何建立一個标題

1. 有關内容的标題在建立的時候需要建立有正确的文法。
2. 單擊頁面中的菜單選項（這個隻針對正常主題和文章進行顯示，如果你試回複和私信的話，這個選項将不會被顯示）。
3. 插入到主題頁面中

當我們使用 Toc 的時候，閱讀進度小元件會發生什麼

你可能知道，在頁面中我們沒有辦法同時顯示閱讀程序和 TOC 。

官方的解決方案是，如果你再閱讀第一個文章的時候，TOC 存在的話，那麼頁面上将隻會顯示 TOC，而将閱讀進度元件忽略而不顯示。

當你的閱讀超過第一個文章的時候，TOC 将不會進行顯示，取而代之的是整個内容的閱讀進度顯示條。

簡單來說，TOC 隻針對第一個文章有效，後續的文章将會使用閱讀進度條。

針對移動終端盒桌面應用的顯示是相同的。

使用這個元件會有什麼問題

針對作者和官方的說法，使用這個元件目前還沒有遇到任何問題。

所有的内容顯示是在用戶端完成的，用行話來說，就是所有的内容是在前端完成的，是以後端的資料提供沒有受到任何的影響。

當你禁用這個元件以後，所有的内容将會恢複成原樣。

使用限制

這個元件使用的是标準的主題布局。

如果你使用的布局對對标題的使用進行了修改的話，那麼這個 TOC 元件将沒有辦法正常工作。

例如已知的，如果使用了 Vincent theme 這個主題的情況下，這個元件是沒有辦法正常工作的。

針對一些非常流行的主題支援，對官方這個插件來說是下一個需要考慮的内容和反向。

開發者

官方的作者是基于 Greg Franko’s tocify.js 庫進行開發的。

但是，非常不幸的是，這個庫已經很長時間沒有更新了，是以作者針對這個庫的内容删除了很多不需要的内容和沒有必要的特性和代碼後把相關的特性整合到 Discourse 中了。

整個元件的大小在 ~ 4kb 左右（使用 gzip 壓縮的情況）。

作者也感謝 @erlend_sh 提出了很多很好的建議和 @david 幫助完成了翻譯工作。

需要改進的（TODO）

• 在編輯的時候，實時對照顯示 TOC （這個可能對資源的消耗非常大）
• 支援一些主流的主題來顯示 TOC
• 單擊标題的連結按鈕同時還自動拷貝到剪貼闆中。

針對這個版本的釋出，作者表示的是：這個釋出還是比較早期的釋出，如果你對這個元件有什麼問題，建議和改進的話，歡迎直接和原作者取得聯系。