In the daily operation of websites, especially when publishing long articles, adding a clear table of contents (or content navigation) is crucial for improving user experience.It can not only help visitors quickly understand the structure of the article and conveniently jump to the chapters of interest, but can also optimize the page SEO performance to a certain extent.AnQiCMS provided a very practical feature that allows us to easily implement the directory display of article content in the front-end template.

Understanding how AnQiCMS generates the table of contents

When processing article content, AnQiCMS will intelligently parse the title tags within the content (such as<h1>/<h2>/<h3>These title information is extracted and provided to the front-end template in a structured data format, which is what we call it.ContentTitlesThis feature is particularly suitable for article detail pages, allowing visitors to clearly understand the structure of the article.

Steps to display the article catalog in the front-end template

To display the article catalog in the AnQiCMS front-end template, it mainly involves locating the template file, obtaining catalog data, and iterating over and rendering these data.

First step: Locate the article detail page template

Firstly, we need to find the template file corresponding to the article detail page. According to the template production conventions of AnQiCMS, the template for the article detail page is usually located in the template directory.{模型table}/detail.htmlEnglish, or you can set the custom template file for specific articles or categories in the background.

Step 2: UsearchiveDetailtags to getContentTitlesdata

In the article detail page template, AnQiCMS providesarchiveDetailLabel to retrieve detailed information about the current article, which includesContentTitles.ContentTitlesReturns an array (a slice in Go language), where each element represents a title from the article content and includes the following key information:

  • Title: Title text content.
  • Tag: Title's HTML tag type, such as 'H2', 'H3', etc.
  • Level: Title's level, usually H1 is level 1, H2 is level 2, and so on.
  • Prefix: Title prefix that may exist, such as automatically generated serial numbers “1.”, “1.1.”, etc.

You can obtain this data in the following ways:

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

Here, we assign the directory data we get tocontentTitlesthis variable for future use.

Step 3: Render the directory by looping

Get tocontentTitlesAfter the variable, because it is an array, we need to use the AnQiCMS template engine'sforLoop through the tags to iterate it, and render each title information to the page. When rendering, we can combine the properties of each title to control the hierarchical display and style of the catalog.TagandLevel属性来控制目录的层级显示和样式。

For example, you can build your article directory like this:

{# 假设您在文章详情页的侧边栏或内容顶部显示目录 #}

{%- archiveDetail contentTitles with name="ContentTitles" %} {# 获取当前文章的目录数据，并赋值给 contentTitles 变量 #}
{%- if contentTitles %} {# 只有当存在目录数据时才显示目录框 #}
<div class="article-toc"> {# 这是目录的容器，您可以根据需要添加CSS类进行样式控制 #}
    <h3>文章目录</h3>
    <nav>
        <ul>
        {% for item in contentTitles %}
            {#
                item.Tag: 标题的HTML标签，如"H2", "H3"
                item.Level: 标题的层级，如2, 3
                item.Prefix: 标题前缀，如"1.", "1.1."
                item.Title: 标题的纯文本内容
                `slugify` 过滤器是假设存在的一个用于生成URL友好ID的过滤器。
                如果AnQiCMS模板中没有内置类似功能，您可能需要手动确保HTML内容中的标题有对应的ID，或者使用JavaScript在前端动态生成锚点。
            #}
            <li class="toc-item toc-{{ item.Tag | lower }}" style="margin-left: {{ (item.Level - 1) * 15 }}px;">
                <a href="#{{ item.Tag | lower }}-{{ item.Title | slugify }}">{{ item.Prefix }} {{ item.Title }}</a>
            </li>
        {% endfor %}
        </ul>
    </nav>
</div>
{%- endif %}

In the above code, we:

  • Use{%- ... %}Use syntax to remove blank lines generated by tag, keeping the HTML output neat.
  • Pass{% if contentTitles %}Determine, make sure that the table of contents is displayed only when the article indeed has a title.
  • Added for each catalog itemtoc-itemandtoc-h2CSS class for (or other tag name), as well as based onitem.Levelinlinemargin-leftStyle, so that the directory level feeling can be easily achieved through CSS.
  • response for<a>TagshrefAttribute generates an anchor link.It should be particularly noted that in order for this anchor link to be effective, the actual title (such as<h2>文章标题</h2>) in your article content must also have the correspondingidattributes, for example<h2 id="h2-文章标题">文章标题</h2>.AnQiCMS in content rendering will usually automatically add IDs to the title, but the specific generation rules may need to be confirmed or consulted in detailed development documents during actual testing.slugifyFilter, if AnQiCMS does not provide, you may need to handle it yourself.

Further optimization and beautification

  • CSS style customization:You can modify according to your website design,.article-toc/.toc-item/.toc-h2English CSS classes, to adjust the appearance of the directory such as font, color, background, indentation, etc.
  • English JavaScript interaction:To provide a better user experience, you can also introduce JavaScript code to achieve this:
    • Smooth scrolling:When you click on an item in the catalog, the page smoothly scrolls to the corresponding chapter.
    • Highlight the current chapter:Automatically highlight the current screen visible area directory items when the user scrolls the page.
    • Fold/Expand the catalog:For articles with many title levels, provide a feature to fold and expand the table of contents.

Through these steps and optimization suggestions, you can easily implement a complete and beautiful article catalog in the AnQiCMS front-end template, thereby significantly enhancing the reading experience of the website content.

Common Questions (FAQ)

  1. Why didn't the directory show up on the front-end page even though I followed the steps and added the code?Firstly, please confirm whether your article content actually uses H1, H2, H3, and other title tags. AnQiCMS'sContentTitlesThe feature is to extract directory information based on these title tags.Check whether you have added code in the template file of the article detail page, and there are no syntax errors in the file path and code itself.Finally, if your article content is entered through a Markdown editor, please make sure that Markdown editor support is enabled in the global settings of the backend.

  2. Clicking on the catalog item does not allow the page to jump to the corresponding title position, why is that?This is usually because the catalog link'shrefattribute (anchor) does not match the actual title in the article contentidThe property does not match. To make the anchor jump effective, each directory item's<a>Tagshrefvalue (for example#h2-文章标题) must correspond to the title in the article content.idattribute values (for example<h2 id="h2-文章标题">文章标题</h2>Completely consistent.AnQiCMS usually automatically generates IDs for titles in the content, but in some custom cases, you may need to check and ensure they match.If AnQiCMS does not automatically add IDs to the titles, you may need to modify the article content or dynamically add IDs to the titles using JavaScript on the frontend.

  3. How to implement smooth scrolling to the directory item after clicking, instead of jumping abruptly?Implement smooth scrolling requires the use of front-end JavaScript. You can take advantage of thescrollIntoView()of the method.behavior: 'smooth'Options, or introducing lightweight JavaScript libraries (such as jQuery's)animate()method) to implement.You need to write JavaScript code to listen for the click event on directory items, then get the target anchor, and call the corresponding scroll method.