How to effectively organize the structure of long articles and enhance the reading experience when managing website content with Anqi CMS is a question worth paying attention to.Automatically generated 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 of interest, while also helping search engines better understand the structure of the article.

The AnQi CMS provides support for Markdown syntax in content management and cleverly utilizes this feature to extract hierarchical title information from Markdown-written content, thereby generating a navigable article table of contents. This means that as long as you use Markdown headings reasonably while editing the article, #/##/###and so on), the system can help us build this catalog.

Open the Markdown editor: Preparations

Before starting to generate the table of contents, we need to ensure that the Markdown editor feature has been enabled in the Anqi CMS backend.This setting is usually found under "Background -> Global Settings -> Content Settings".After enabling, the content you edit will be recognized by the system as Markdown format and processed accordingly.

Core Mechanism: How AnQiCMS parses Markdown content

The strength of AnQi CMS lies in its powerful 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 during article rendering,<h1>/<h2>/<h3>These titles will also extract their metadata. This metadata is througharchiveDetailthe tag inContentTitlesThe field is exposed to the template, it is an array object that contains the text of each title, the type of HTML tag (such as h1, h2), hierarchy, and possibly a custom prefix. It is thisContentTitlesAn array, which provides the basic data for automatically generating the catalog.

Build the article catalog (TOC) in the template.

To display the extracted title information as clickable article contents, we need to perform operations in the corresponding template file, usually in the article detail page template (such as){模型table}/detail.html）to be performed.

Firstly,archiveDetailTags to get articles.ContentTitlesData:

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

IfcontentTitlesThe array is not empty, indicating that there is a title in the article. At this point, we can start building the table of contents. Below is a simple code example showing how to iterateContentTitlesGenerate 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 detailed information of the current article and assigns it tocontentTitlesa variable.
  2. {% if contentTitles %}Check 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 semantically marked HTML tag used to wrap article contents, making it convenient to apply CSS styles.
  4. {% for item in contentTitles %}TraversalcontentTitleseach title item in the array.
  5. <li class="toc-level-{{ item.Level }}">Generate a list item for each directory entry and,item.LevelAdd different CSS classes for (title levels, such as 1 representing h1, 2 representing h2) to help us control the indentation and appearance of the directory through the stylesheet, making it more hierarchical.
  6. <a href="#{{ item.Title|urlencode|lower|replace:" ","-" }}" title="{{ item.Title }}">This is the core part of the catalog item, create a hyperlink.
    • href="#..."The link targets an in-page anchor. We assume that the AnQi CMS Markdown parser will automatically assignhAdd a title text-based ID to the label (for example## 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, we performitem.Titleseveral 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 }}"Addtitleproperty, providing tooltip information on mouse hover.
  7. {% if item.Prefix %}{{ item.Prefix }} {% endif %}{{ item.Title }}: Display the text content of the title.item.Prefix[en] It is optional and will be displayed if it exists.

[en] Suggestions for style adjustment:

[en] To make the article directory look nice and easy to use on the page, you can adjust the CSS for.article-tocand.toc-level-XDefine styles for similar elements, such as setting borders, background color, font size, indentation, 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注意事项

  • Standard Usage of Markdown TitlesEnsure that the author 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 selection of the catalog position: 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 throughincludeEmbed this directory code at 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 issues with directory links not jumping after clicking, it may be necessary to check if the Markdown renderer provides