example
desktop
Mobile terminals
characteristic
toc = table of contents
- Through the settings button above the menu, a TOC list is generated with one click according to the status of the current content
- The TOC will always be displayed on the page - the scrolling content is synchronized with the link to the topic
- When you scroll through a topic in the current page, the list of content corresponding to that topic will be highlighted (shown in green)
- Add attributes to the title (you can link to specific content from other topics/posts)
- By clicking the topic link to the TOC, the browser navigates to the corresponding location of the body content (synchronous scrolling)
- Add a link for each title that you can copy (if you wish, of course)
- RTL support
- The color scheme is based on the color scheme you are currently using
How it works
By default, the title of the current content will be marked as toc (done above via the composer button), and if your current topic is marked, this will also be converted to toc (this is related to the hierarchy of the current title), and all content titles will be converted to TOC - this means that the title settings of your MD file must be correct, and if your title setting level is wrong, the result of the conversion will also be wrong.
# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6
You can adjust the hierarchy as much as you like, but you have to make sure the level is correct.
# heading 2
## heading 3
## heading 3
### heading 4
## heading 3
# heading 2
etc...
For links to work properly, all headers must have an id attribute.
This component will automatically verify the ID of the title, and if the title exists, then this component will be able to execute more efficiently. Ids are also more useful when you create a theme manually.
If your title does not have an ID, this component will automatically create an ID based on the content of the title (unwanted characters will be automatically ignored).
When all of the above is done, TOC will create a link to the body based on the title, as shown below:
Set up
This component has only one setting, which is the icon of the TOC (this image will be used in later settings, and it is not recommended to modify this icon. ）
Translation and localization
This component also needs to translate very little content, only the following 3 fields need to be translated.
table_of_contents: "table of contents（内容列表）"
This will be displayed when TOC is opened on the mobile terminal
insert_table_of_contents: "Insert table of contents（插入内容列表）"
This is displayed when the content list 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 on the preview page when you edit the theme content, while previewing on the right. This is the text that shows up in the composer preview to indicate that the a toc will be generated for the topic
How to create a title
- The title of the content needs to be created with the correct syntax when it is created.
- Click on the menu option on the page (this is only displayed for regular topics and posts, if you try replies and private messages, this option will not be displayed).
- Insert into the theme page
When we use Toc, read what happens with the progress widget
As you may know, we don't have a way to display both the reading progress and the TOC on the page.
The official solution is that if the TOC exists when you read the first post, only the TOC will be displayed on the page, and the reading progress component will be ignored and not displayed.
When you read more than the first post, the TOC will not be displayed, but will be replaced by a reading progress bar for the entire content.
In simple terms, the TOC is only valid for the first post, and subsequent posts will use the reading progress bar.
The display is the same for mobile terminal box desktop applications.
What are the problems with using this component
To the author and the official version, there have been no problems 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 data provision on the back end is not affected in any way.
When you disable this component, everything will revert to its original state.
Usage Restrictions
This component uses a standard theme layout.
If you use a layout that modifies the use of headings, this TOC component will not work properly.
For example, it is known that this component will not work properly if the Vincent theme is used.
Support for some very popular themes, for the official plugin is the next thing to consider and reverse.
Developers
The official author is based on Greg Franko's tocify.js library.
However, unfortunately, this library has not been updated for a long time, so the author removed a lot of unnecessary content and unnecessary features and code for the content of this library and integrated the relevant features into Discourse.
The size of the entire component is around ~4kb (in the case of gzip compression).
The author also thanks @erlend_sh for his good suggestions and @david for helping with the translation.
Needs Improvement (TODO)
- At the time of editing, the TOC is displayed in real time (this can be very resource consuming)
- Support for some mainstream themes to display TOC
- Clicking the link button for the title is also automatically copied to the clipboard.
For the release of this version, the author said: this release is still a relatively early release, if you have any questions, suggestions and improvements to this component, welcome to contact the original author directly.