How to automatically generate an article table of contents (TOC) based on Markdown content?

How to effectively organize the structure of long articles when using Anqi CMS to manage website content, and improve the reading experience of readers, is a question worth paying attention to.Automatically generate the article table of contents (Table of Contents, abbreviated as TOC) is a very practical solution.It not only allows readers to quickly understand the outline of the article, but also makes it convenient for them to jump to the parts they are interested in, and also helps search engines better understand the structure of the article.

AnQi CMS provides support for Markdown syntax in content management and cleverly utilizes this feature to extract title hierarchy information from Markdown content, thereby generating a navigable article directory. This means that as long as you use Markdown headings reasonably while editing the article, ...#/##/###etc.), the system can help us build this directory.

Open the Markdown editor: preperation

Before starting to generate the table of contents, we need to make sure that the Markdown editor function has been enabled in the AnQi CMS backend.This setting is usually found in "Background->Global Settings->Content Settings".After enabling, the content of the article you edit will be recognized by the system as Markdown format, and subsequent parsing will be performed.

Core Mechanism: How does AnQiCMS parse Markdown content

The strength of AnQi CMS lies in its template engine's deep parsing capability for Markdown content. When you write articles using Markdown syntax, for example:

# 这是一个一级标题
## 这是二级标题
### 这是三级标题

The system not only converts these Markdown headings to corresponding HTML tags when rendering articles,<h1>/<h2>/<h3>It will also extract the metadata of these titles. This metadata is througharchiveDetailin the labelContentTitlesThe field is exposed to the template, it is an array object that contains the text of each title, the HTML tag type (such as h1, h2), level, and possibly a custom prefix. It is thisContentTitlesArray, it provides the basic data for automatically generating the catalog.

Build the article catalog (TOC) in the template.

We need to display these extracted title information as clickable article contents in the corresponding template file, usually in the article detail page template (such as{模型table}/detail.htmlbeing performed.

First, througharchiveDetailTags to retrieve articles.ContentTitlesData:

{% archiveDetail contentTitles with name="ContentTitles" %}

IfcontentTitlesThe array is not empty, indicating that the article contains a title. At this point, we can start building the table of contents. Below is a simple code example showing how to traverseContentTitlesGenerate a basic directory:

{% archiveDetail contentTitles with name="ContentTitles" %}
{% if contentTitles %}
<nav class="article-toc">
    <h3>文章目录</h3>
    <ul>
        {% for item in contentTitles %}
        <li class="toc-level-{{ item.Level }}">
            <a href="#{{ item.Title|urlencode|lower|replace:" ","-" }}" title="{{ item.Title }}">
                {% if item.Prefix %}{{ item.Prefix }} {% endif %}{{ item.Title }}
            </a>
        </li>
        {% endfor %}
    </ul>
</nav>
{% endif %}

Let's explain this piece of code:

1. {% archiveDetail contentTitles with name="ContentTitles" %}: This line of code retrieves the list of all titles from the details of the current article and assigns it tocontentTitlesVariable.
2. {% if contentTitles %}: Determine if the article has a title, and render the table of contents only if it exists to avoid empty tables of contents.
3. <nav class="article-toc">...</nav>: This is a semantic HTML tag used to wrap the article catalog for easy styling control with CSS.
4. {% for item in contentTitles %}: TraversecontentTitlesEach item in the array.
5. <li class="toc-level-{{ item.Level }}">: Generate a list item for each directory item and according toitem.Level(Header levels, such as 1 representing h1, 2 representing h2) Add different CSS classes, which helps us control the indentation and appearance of the catalog through style sheets, making it more hierarchical.
6. <a href="#{{ item.Title|urlencode|lower|replace:" ","-" }}" title="{{ item.Title }}">: This is the core part of the directory item, create a hyperlink.
   • href="#...": The target of the link is an in-page anchor. We assume that the Anqi CMS Markdown parser will automatically convert the Markdown headings to HTML whenhAdd a tag with an ID based on the title text (such as## My HeadingIt will be rendered as:<h2 id="my-heading">My Heading</h2>)
   • item.Title|urlencode|lower|replace:" ","-": To ensure that the generated anchor ID is valid, weitem.Titlehave performed several processes:
     • urlencode: Encode special characters in the title to avoid link errors.
     • lower: Convert the title to lowercase.
     • replace:" ","-": Replace spaces in the title with hyphens.-This is a common way to generate URL slugs and anchor IDs.
   • title="{{ item.Title }}"AddtitleAttribute, providing hover tips.
7. {% if item.Prefix %}{{ item.Prefix }} {% endif %}{{ item.Title }}: Display the text content of the title.item.PrefixOptional, if present, it will be displayed.

Suggestion for style adjustment:

To make the article directory beautiful and easy to use on the page, you can adjust it through CSS..article-tocand.toc-level-XDefine styles for classes, for example, set borders, background colors, font sizes, indents, etc., to maintain consistency with the overall design style of the website.

/* 示例 CSS 样式 */
.article-toc {
    border: 1px solid #eee;
    padding: 15px;
    margin-bottom: 20px;
    background-color: #f9f9f9;
}
.article-toc h3 {
    font-size: 18px;
    margin-top: 0;
    margin-bottom: 10px;
    color: #333;
}
.article-toc ul {
    list-style: none;
    padding-left: 0;
}
.article-toc ul li {
    line-height: 1.8;
}
/* 不同层级标题的缩进 */
.toc-level-1 { padding-left: 0; font-weight: bold; }
.toc-level-2 { padding-left: 15px; }
.toc-level-3 { padding-left: 30px; }
.toc-level-4 { padding-left: 45px; }
/* ...更多层级 */

Practical skills and precautions

• Standard use of Markdown titlesEnsure that the author of the article always follows the semantic use of Markdown headings when writing content, that is, the first-level heading is used for the main theme of the article, and the second and third-level headings are used for chapter division, with clear levels.
• The choice of catalog location: The article catalog is usually placed at the beginning of the article content or in the sidebar, so that readers can see it at a glance. You can throughincludeLabel this directory code in the appropriate position in the article detail template.
• CompatibilityThe above method relies on the built-in Markdown parser of Anqi CMS to automatically add predictable ID attributes to the generated HTML titles. If you encounter a problem where the directory links cannot be clicked to jump, you may need to check whether the Markdown renderer provides