|||
|-|-|-|
| Overview | DiscoTOC allows you to create a table of contents for your topic with one click.
| 
| Preview | Beginner's guide to using Discourse Themes (Please visit the link in a new tab) |
| Repo Link | https://github.com/discourse/DiscoTOC
| No knowledge of Discourse themes? | Please visit the official webpage for the Beginner’s guide to using Discourse Themes.
Example
Desktop
Mobile
Features
toc = table of contents
- Create a toc list with one click via the settings button above the menu, based on the current content.
- The Toc will always be displayed prominently on the page — scrolling content and topic links are synchronized.
- When you scroll past a topic in the current page, the corresponding table of contents will be highlighted (displayed in green).
- Add attributes to headings (you can link to specific content from other topics/posts).
- Clicking on a toc topic link will navigate the browser to the corresponding position in the main content (synchronized scrolling).
- Add a copyable link to each heading (if desired).
- RTL support.
- Color scheme is based on your current color scheme.
How it Works
By default, the headings of the current content will be marked as toc (done via the composer button). If your current topic is marked, it will also be converted to toc (this depends on the hierarchy of the current heading). All content headings will be converted to TOC — this means that the heading settings in your MD file must be correct. If the heading hierarchy is incorrect, the conversion result will also be incorrect.
# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6
You can adjust the hierarchy as you wish, but you must ensure the hierarchy is correct.
# heading 2
## heading 3
## heading 3
### heading 4
## heading 3
# heading 2
etc...
To ensure the links work correctly, all headings must have an Id attribute.
This component will automatically validate the heading IDs. If the heading exists, the component will execute more effectively. IDs are also more useful when you manually create topics.
If your heading does not have an Id, this component will automatically create an Id based on the heading content (unnecessary characters will be automatically ignored).
Once all the above is completed, TOC will create a link to the main content based on the headings, as shown below:
Settings
This component has only one setting: the Toc icon (this image will be used in subsequent settings, and the official recommendation is not to modify this icon.)
Translation and Localization
This component requires very little translation, with only the following 3 fields needing translation.
table_of_contents: "table of contents"
This will be displayed when opening the TOC on mobile devices.
insert_table_of_contents: "Insert table of contents"
This will be displayed when the table of contents is inserted into the topic page.
topic_will_contain_a_table_of_contents: "This topic will contain a table of contents"
This content will be displayed in the preview page on the right when you are editing the topic content.
How to Create a Heading
- Headings for content need to be created with correct syntax when created.
- Click the menu option on the page (this only displays for regular topics and posts; it will not be displayed for replies or private messages).
- Insert into the topic page.
What Happens to the Reading Progress Widget When We Use Toc
As you may know, we cannot display both reading progress and TOC simultaneously on the page.
The official solution is that if the TOC exists when reading the first post, only the TOC will be displayed on the page, and the reading progress widget will be ignored and not displayed.
When you scroll past the first post, the TOC will not be displayed; instead, the entire content’s reading progress bar will be displayed.
In simple terms, TOC is only effective for the first post; subsequent posts will use the reading progress bar.
The display is the same for mobile and desktop applications.
Any Issues with Using This Component?
According to the authors and the official sources, no issues have been encountered with using this component so far.
All content display is done on the client side, in jargon, all content is done on the front end, so the backend data provision is not affected in any way.
When you disable this component, all content will revert to its original state.
Usage Limitations
This component uses standard theme layouts.
If your layout modifies the use of headings, this TOC component will not work correctly.
For example, it is known that this component does not work correctly with the Vincent theme.
Support for some very popular themes is something that the official plugin will consider in the future.
Developer
The official author developed it based on Greg Franko’s tocify.js library.
However, unfortunately, this library has not been updated for a long time, so the author has removed a lot of unnecessary content, features, and code from the library and integrated the relevant features into Discourse.
The size of the entire component is about ~ 4kb (when compressed with gzip).
The author also thanks @erlend_sh for many good suggestions and @david for helping with the translation.
To Be Improved (TODO)
- Real-time display of TOC during editing (this may consume a lot of resources).
- Support for some mainstream themes to display TOC.
- Copy the link button for clicking on headings to the clipboard automatically.
Regarding the release of this version, the author states: this is an early release. If you have any questions or suggestions for improvement regarding this component, you are welcome to contact the original author directly.
For official information, links, and discussions about this component, please refer to the content on the page: DiscoTOC - automatic table of contents.
Technical Help (Chinese)
If you have any other questions or need help, please visit our website (Chinese): iSharkFly - 飞鲨