How to generate the catalog navigation on the front page for the automatic extraction of article content (`ContentTitles`) feature?

In AnQi CMS, to help readers better understand the structure of long articles, providing a clear table of contents is the key to improving user experience. AnQi CMS automatically extracts titles from the article content (ContentTitlesThis feature was created for this very purpose. It can intelligently identify the various levels of headings 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.

UnderstandingContentTitlesFeature

ContentTitlesIsarchiveDetailA powerful attribute provided by the tag. When we use it on the article detail pagearchiveDetailLabel to retrieve the current article content, it will not only return the main content, title, description and other information of the article, but will also particularly provide a name forContentTitlesThe field. This field contains all the text identified as titles in the article and their corresponding hierarchy information.

To be specific,ContentTitlesAn array (or list) will be returned, each element of which is an object containing the following information:

• Title: The text content of the title.
• Tag: The HTML tag type for headings, for example 'H1', 'H2', 'H3', etc.
• Level: The level of the title, for example, 1 represents H1, 2 represents H2, and so on. This is crucial for building nested directories.
• PrefixIf the title has a prefix (such as automatic numbering), it will be included here.

By these structured data, we can precisely know which titles are in the article, as well as their hierarchical relationships, providing a solid foundation for generating the catalog navigation.

Why is the article catalog navigation so important?

The article catalog navigation is not just an aesthetic element, it plays multiple roles in content operation:

• Improve user experience:Readers can easily see the outline of the article, quickly jump to the chapters of interest, especially for long articles, which greatly reduces the trouble of scrolling to search.
• Optimize SEO:Search engines prefer content that is structured clearly and easy to crawl. The directory navigation can help search engines better understand the topic and structure of the article, which is helpful for improving the ranking of the content.
• Increase the page stay 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 directory navigation on the front-end page.

To utilizeContentTitlesThe function generates directory navigation on the front end, mainly involving the following steps:

1. Obtain in the article detail templateContentTitlesData:Firstly, we need to be in the article detail page template file (usually{模型table}/detail.htmlUse it inarchiveDetailTag to get the list of article titles.

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

   Here, we assign the extracted title data to.contentTitlesthis variable.

2. the judgment.ContentTitlesIs empty and start building the directory structure:After obtaining tocontentTitlesAfter the variable, we usually check if it contains any titles.If the article does not detect a title (for example, only plain text is used), then the table of contents navigation does not need to be displayed.If there is a title, we can start using HTML's<ul>and<li>Tag to build the list structure of the catalog.

   {% 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 catalog items:Next, we need to useforto loop throughcontentTitlesOf each title object, and generate a list item for each title. At the same time, in order to achieve smooth page jumping to the corresponding title position when 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 contentidProperty.

   A common 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 uniqueidattribute (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 directory items, we can base them onitem.Title(Title Text) anditem.LevelTo dynamically generate aid. For example, you can build it like this:toc-+标题文本+-+层级comma and process the title text by replacing spaces with hyphens, converting to lowercase, making 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 %}
   

   This has been usedreplace:" ","-"|lowerA filter 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 style and interaction (optional but recommended):After completing the HTML structure, you can add style to the directory navigation using CSS to make it more visually appealing. For example, according tolevel-XThe class name indents the titles at different levels. You can also choose to use a JavaScript library or a custom script to implement some advanced interactive features such as:

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

Complete code example (HTML/Twig part only):

This is your article in a JSON object