In daily website operations, we often encounter long-form content such as tutorials, product descriptions, or in-depth analysis articles.At this point, it is particularly important to add a clear table of contents to the article (usually located in the sidebar or at the top of the article).It not only helps visitors quickly understand the structure of the article, directly jump to the part of interest, but also improves the SEO performance of the page and enhances the user experience.In AnQiCMS (AnQiCMS), implementing this feature is actually simpler than you imagine, thanks to a very practical template tag provided by the system.

The core feature revelation:ContentTitlesThe clever use of tags

AnQi CMS considers the display of content very carefully and provides a tag namedContentTitlesThe special field. This field is not used to display article content, but is specifically used to extract information about all title levels (H1 to H6) from the article content and provide it to us in a structured data format, which is very suitable for dynamically generating article directory navigation.

When we usearchiveDetailto obtain article details by specifyingname="ContentTitles"The system will intelligently parse the article content, packaging all recognized titles (including title text, HTML tags, levels, and possible prefix numbers) into an array for us to call in the template.

Specific implementation steps

To utilizeContentTitlesTag building directory navigation, usually it can be divided into the following steps:

Step one: Ensure that the article content has a clear title structure

When editing article content on the Anqi CMS backend, whether using the rich text editor to set H1-H6 titles (for example, through the "Set Title/Text" function), or writing content using Markdown editor and using#/##The equal sign defines the title, the system will automatically recognize and save the structural information of these titles. This isContentTitlesThe basis for the label to work properly. Make sure that your article content is organized according to the HTML title specification (H1-H6).

Step two: Call in the template.ContentTitlesGet Title List

Then, in the article detail page template (usually{模型table}/detail.htmlIn the document template you have customized, we need to find the right place to insert the table of contents navigation. For example, you may want it to display in the sidebar of the article text or at the top.

In the template, we can call it like thisContentTitlesField:

{% archiveDetail contentTitles with name="ContentTitles" %}
    {# 此处将接收到一个名为 `contentTitles` 的数组变量 #}
    {# 接下来我们将遍历这个数组来构建目录 #}
{% endarchiveDetail %}

Here, we usearchiveDetailThe tag obtained the current article'sContentTitlesdata and assigned it to a variable namedcontentTitlesto the template. ThiscontentTitlesNow the variable contains all the detailed information of the article's titles.

Step 3: Traverse and build the directory navigation

After obtaining the title data, we just need to use a simpleforloop to build the directory navigation.contentTitlesEach element in the array is an object that contains the following useful properties:

  • TitleThe actual text content of the title.
  • Tag: The HTML tag of the title, for example, "H1", "H2", etc.
  • Level: The level of the title, where the number 1 represents H1, 2 represents H2, and so on.
  • Prefix: If the title has automatic numbering, it will include a prefix (such as "1.1").

Using these properties, we can create a structured list:

{% archiveDetail contentTitles with name="ContentTitles" %}
    {% if contentTitles %} {# 检查是否有标题，避免空目录 #}
        <div class="article-toc">
            <h4>文章目录</h4>
            <ul class="toc-list">
                {% for item in contentTitles %}
                    <li class="toc-item toc-level-{{ item.Level }}">
                        <a href="#{{ item.Title|urlencode|lower|replace:"%20","-" }}" title="{{ item.Title }}">
                            {% if item.Prefix %}{{ item.Prefix }} {% endif %}{{ item.Title }}
                        </a>
                    </li>
                {% endfor %}
            </ul>
        </div>
    {% endif %}
{% endarchiveDetail %}

In the above example, we created a simple unordered list as a directory. Bytoc-level-{{ item.Level }}Such CSS class names, you can easily add different indentation styles to different levels of headings, making the directory structure clear at a glance. At the same time, we have generated a directory item for each one.hrefThe attribute, by usingitem.TitleURL encoding, converting to lowercase, and replacing spaces with hyphens, creates a simple anchor link.

Optimization and Advanced

To make your directory navigation feature more perfect, there are still some optimization suggestions that can be considered:

  1. Implement clickable anchor links: Just generating a directory list is not enough. After clicking on a directory item, the page should smoothly scroll to the corresponding title position. This requires adding a unique identifier to the actual title elements in the article (such as<h2>/<h3>etc.idProperty, and thisidShould be in the directory navigation<a>label'shrefThe properties match. You can dynamically add an ID to the title using front-end JavaScript when the page loads, or use a similar method to generate it on the server sideitem.Title|urlencode|lower|replace:"%20","-"in the mannerid.
  2. Styled CatalogueUtilizeitem.LevelAttribute, you can flexibly add CSS styles to directory items at different levels, for example, by increasing the left margin to simulate a tree structure, which improves the readability and aesthetics of the directory.
  3. Conditional Display of Directory: If the article content is short, or the number of titles is not many, it may not be necessary to display the directory. You can use it in the template.{% if contentTitles|length > 某个数量 %}To determine the number of titles, the table of contents is displayed only when there are enough titles.

By following these steps and optimizations, you can easily generate a complete, beautiful, and practical directory navigation for article content in Anqi CMS, significantly enhancing the user experience and content value of the website.

Frequently Asked Questions (FAQ)

  1. Ask: Why is my article directory navigation not displaying any content?Answer: First, please check if your article content includes H1 to H6 title tags. If the article does not use any titles,ContentTitlesThe label cannot naturally extract the data. Secondly, confirm that you have used the template file correctlyarchiveDetail contentTitles with name="ContentTitles"label, and iterate through the loopcontentTitlesThe code of the variable is correct. Sometimes, cache issues may cause content to not be updated in time, you can try to clear the system cache.

  2. How do I make the directory item click scroll to the corresponding title, rather than just jumping to the top of the page?This requires setting the actual title element in the article content (for example<h2>我是标题</h2>Add a uniqueidproperty. You can use the ID that matches thehrefproperty, for exampleid="我是标题"(URL-friendly). On the front end, you can write JavaScript code to iterate over these titles and generate IDs for them when the page loads, or ensure that the titles have predictable IDs when rendering the article content on the back end.This, in the directory of<a>label to accesshref="#对应的ID"and point to a specific title within the page.

  3. Question:ContentTitlesThe label will get which levels of titles?Answer:ContentTitlesThe tag is very intelligent, it will automatically identify and return all the HTML standard title levels in the article content, that is, from H1 to H6 all the title information. Initem.LevelIn the properties, you will see the corresponding number level, for example, H1 corresponds to 1, H2 corresponds to 2, and so on.