In AnQi CMS, to help readers better understand the structure of long articles, providing a clear table of contents is crucial for enhancing user experience. AnQi CMS automatically extracts titles (ContentTitlesFunction, it is for this.It can intelligently identify the various titles in the article content and provide this structured information to the front-end template, thereby allowing us to easily build a dynamic and practical directory navigation.

UnderstandingContentTitlesFunction

ContentTitlesYesarchiveDetailLabel provides a powerful attribute. When we use it in the article detail page,archiveDetailWhen fetching the current article content with tags, it not only returns the main content, title, description and other information of the article, but also specially provides a namedContentTitlesThe field. This field contains all the text identified as titles in the article and their corresponding hierarchical information.

To be specific,ContentTitlesIt will return an array (or list), where each element is an object containing the following information:

  • Title: Title text content.
  • Tag: 标题的HTML标签类型，例如 “H1”, “H2”, “H3” 等。
  • Level: Title hierarchy, for example 1 represents H1, 2 represents H2, and so on. This is crucial for building nested directories.
  • Prefix: If the title has a prefix (such as automatic numbering), it will be included here.

Through these structured data, we can precisely know which titles are in the article and their hierarchical relationships, providing a solid foundation for generating table of contents navigation.

Why is the table of contents navigation so important?

The table of contents navigation is not just an aesthetic element; it plays multiple roles in content operation:

  • Enhance user experience:Readers can easily see the outline of the article and quickly jump to the chapters of interest, especially for long content, which greatly reduces the trouble of scrolling to find.
  • Optimize SEO:Search engines prefer content that is structured clearly and easy to crawl. Directory navigation can help search engines better understand the theme and structure of the article, which is helpful for improving the ranking of the content.
  • Increase page dwell time:Convenient navigation makes it easier for users to immerse themselves in the content, reducing the bounce rate.
  • Assist in content creation:Remind the author to pay attention to the title hierarchy and logic when writing articles, so as to produce higher quality content.

Steps to generate a table of contents navigation on the front page

To make use ofContentTitlesThe navigation directory is generated on the front-end, mainly involving the following steps:

  1. Obtained in the article detail templateContentTitlesData:Firstly, we need to be in the template file of the article detail page (usually){模型table}/detail.html), usearchiveDetailLabel to get the article title list.

    {% archiveDetail contentTitles with name="ContentTitles" %}
    {# contentTitles 变量现在包含了文章中所有标题的结构化数据 #}
{% endarchiveDetail %}

    Here, we assign the extracted title data tocontentTitlesthis variable.

  2. JudgmentContentTitleswhether it is empty and start building the directory structure:在获取到contentTitlesAfter the variable, we will usually check if it contains any titles.If the article does not detect a title (for example, only plain text is used), the table of contents navigation does not need to be displayed.<ul>and<li>Label to build the directory list structure.

    {% archiveDetail contentTitles with name="ContentTitles" %}
    {% if contentTitles %}
    <nav class="article-toc">
        <h4>文章目录</h4>
        <ul class="toc-list">
            {# 在这里循环生成目录项 #}
        </ul>
    </nav>
    {% endif %}
{% endarchiveDetail %}

  3. Traverse the title data and create clickable directory items:Next, we need to useforin a loop to iterate overcontentTitlesEach title object, and generate a list item for each title. At the same time, in order to achieve smooth page scrolling to the corresponding title position after clicking on the catalog item, we need to create an anchor link for each catalog item.<a>Label), and points to the corresponding title in the article content.idproperties.

    An automatic practice is that when we insert H1, H2, and other titles into the rich text editor of an article, the editor will automatically generate a uniqueidproperties (for example,id="section-introduction"）。If your editor does not have this feature, you may need to manually ensure that the HTML titles (such as<h2 id="section-introduction">引言</h2>）are uniqueid.

    When generating catalog items, we can base them onitem.Title(Title Text) anditem.Level(Title Level) to dynamically generate aid. For example, you can build it like this:toc-+标题文本+-+层级and process the title text (such as replacing spaces with hyphens, converting to lowercase), to make it URL-friendly.

    {% archiveDetail contentTitles with name="ContentTitles" %}
    {% if contentTitles %}
    <nav class="article-toc">
        <h4>文章目录</h4>
        <ul class="toc-list">
            {% for item in contentTitles %}
                {# 生成一个URL友好的唯一ID，例如：'toc-文章导读-1' #}
                {# 注意：您需要确保文章内容中的对应标题元素也有相同的ID属性，才能实现点击跳转 #}
                {% set sectionId = 'toc-' ~ item.Title|replace:" ","-"|lower ~ '-' ~ item.Level %}
                <li class="toc-item level-{{item.Level}}">
                    <a href="#{{ sectionId }}">{{item.Prefix}} {{item.Title}}</a>
                </li>
            {% endfor %}
        </ul>
    </nav>
    {% endif %}
{% endarchiveDetail %}

    Here, we usereplace:" ","-"|lowerThe filter is used to replace spaces in the title with hyphens and convert it to lowercase to generate a more standardized HTML ID.~The symbol is used to concatenate strings.

  4. Add styles and interactions (optional but recommended):After completing the HTML structure, you can add styles to the navigation menu using CSS to make it visually more appealing. For example,level-XThe class name indents titles at different levels. You can also choose to use a JavaScript library or custom scripts to implement some advanced interactive features, such as:

    • Smooth scrolling:Clicking on the catalog item will cause the page to smoothly scroll to the corresponding title.
    • Highlight the current reading chapter:When the user scrolls the page, the corresponding title item in the catalog will be highlighted to indicate the current reading position.
    • Catalog collapse/expand: Provide a collapse/expand button for a long directory, to keep the page tidy.

Complete code example (HTML/Twig part only):

English version: `twig {# This is your article