Are content directories (ContentTitles) automatically generated and displayed on the article detail page of AnQiCMS?

For long content, a clear content directory (also known as "article outline" or "chapter navigation") can greatly enhance the reading experience of users.It not only helps readers quickly understand the structure of the article, but also allows them to directly jump to the chapters of interest, thereby improving the readability and user satisfaction of the content.AnQiCMS fully considered this requirement and provided a convenient way to automatically generate and display the content directory on the article detail page.

How to get the content directory data in AnQiCMS?

The strength of AnQiCMS lies in its template engine's ability to intelligently parse article content. When you use standard HTML title tags in article editing,<h1>/<h2>/<h3>and, or used in Markdown editors#/##/###Wait for the mark), AnQiCMS will automatically extract these titles and organize them into structured data for template calls.

We need to use it to get this structured content catalog dataarchiveDetailtags, and specifyname="ContentTitles". This tag will return an array containing all the detected title information in the article.

Each item in the array is an object containing the following key information:

  • Title: The text content of the title.
  • Tag: The HTML tag used for the title (for example),H1/H2)
  • Level: The level of the title ("),H1Corresponding to Level 1,H2Corresponding to Level 2, and so on), which is very useful for the indentation and style design of the catalog.
  • PrefixIf the title content contains a serial number (such as “1. Introduction”), the system will automatically extract this prefix.

Steps to display the content directory in the template.

To display the content directory on the article detail page, you need to edit the current detail page template.

Step 1: Find and edit the article detail page template.

In most cases, the template file for the article detail page is located in the current theme directory.archive/detail.htmlOr it is directly.detail.html. If you have customized the article model or the template of a specific article, please find the corresponding template file according to your configuration.

Second step: usearchiveDetailtag to obtainContentTitlesdata

In the template file, find the location where you want to display the content directory (usually above the article content, in the sidebar, or at some appropriate location within the article content). Then, usearchiveDetailThe tag assigns the content directory data to a variable. For example, we can assign it to a variable namedcontentTitles：“

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

Now,contentTitlesThe variable contains the structured data of all titles in the article.

Step three: loop throughcontentTitlesdata and render the catalog

due tocontentTitlesIt is an array, we need to useforloop to traverse it and display each title one by one. In the loop, you can useitem.Title/item.Taganditem.LevelBuild the HTML structure of the catalog.

A basic directory display code may look like this:

{% archiveDetail contentTitles with name="ContentTitles" %}
{% if contentTitles %}
<div class="article-toc">
    <h4>文章目录</h4>
    <ul>
    {% for item in contentTitles %}
        {# 根据层级添加缩进样式，例如使用CSS类或内联样式 #}
        <li class="toc-level-{{ item.Level }}">
            <a href="#{{ item.Title|urlencode }}" title="{{ item.Title }}">
                {% if item.Prefix %}{{ item.Prefix }} {% endif %}{{ item.Title }}
            </a>
        </li>
    {% endfor %}
    </ul>
</div>
{% endif %}

Code explanation:

  • {% if contentTitles %}This is a conditional judgment to ensure that the content directory will be displayed only when there is a title in the article, to avoid the appearance of an empty directory.
  • <div class="article-toc">Create a container for the content directory, which is convenient for CSS style control later.
  • <li class="toc-level-{{ item.Level }}">Here we utilizeitem.LevelGenerate a unique CSS class for each directory item (for exampletoc-level-1/toc-level-2This allows you to easily set different indents, font sizes, or colors for headings of different levels through CSS, thereby intuitively displaying the hierarchical structure of the article.
  • href="#{{ item.Title|urlencode }}"This line of code is to implement smooth scrolling to the corresponding chapter when clicking on the directory item. It assumes that the titles in the article content (created through Markdown or rich text editor) will be automatically or generated by custom JavaScript corresponding to theidProperty, andidValue is related to the title text.|urlencodeThe filter ensures that special characters in the title are correctly encoded for use in URLs.
  • {% if item.Prefix %}{{ item.Prefix }} {% endif %}If the title has a number or dot prefix, it will be displayed here.

Improve the style and interaction of the content catalog.

It is not enough to simply display directory text; you also need to beautify the directory through CSS to make it more readable. For example, you can set differenttoc-level-Xof<li>elements with differentmargin-leftTo achieve indentation effect.

In addition, to achieve smooth scrolling to the corresponding title and highlighting the current reading chapter, and other advanced interactions after clicking on the directory item, it is usually necessary to combine JavaScript to implement.This function can be enhanced to improve user experience by writing some front-end scripts.scrollIntoViewAPI to implement smooth scrolling; or when the page is scrolling, detect the title of the current visible area and add it to the corresponding directory item.activeClass.

By following these steps, you can automatically generate and display a clear and easy-to-navigate content directory on the article detail page of AnQiCMS.

Frequently Asked Questions (FAQ)

1. Why can't my content catalog click to jump to the corresponding chapter?

ContentTitlesThe tag is responsible for extracting the title text and hierarchical information from the article, but it will not automatically generate HTML for these titlesidProperty. To implement click-through, you need to ensure that each title in the article content has a uniqueidProperty.

  • Rich text editor:Some advanced rich text editors may support manually adding titles during editingidor have plugins that can generate them automatically.
  • Markdown editor:If you use a Markdown editor, many Markdown parsers (such as GitHub Flavored Markdown) will automatically format headings (#/##GenerateidProperty. For example,## 我的章节May be interpreted as<h2 id="我的章节">我的章节</h2>. If your Markdown parser does not support it, you may need to add it manually, for example## 我的章节 {#my-chapter}.
  • JavaScript Helper:If the editor cannot generate automaticallyidYou can dynamically iterate over all titles in the article content on the front end using JavaScripth1/h2and generate uniqueidand update the catalog in<a>label'shrefProperty.

2. Why does the table of contents not display even though I clearly used titles in my article content?

First, please check whether the above code snippet has been correctly added to your article detail page template. Secondly, make sure that you are indeed using the standard HTML title tags in your article content (<h1>to<h6>）or the corresponding title marker in Markdown syntax#to######）。If other custom tags are used or it is simply bold text, AnQiCMS will not be able to recognize and extract.Finally, clear the system cache and refresh the page to ensure that the template changes have taken effect.

How is the level of the content directory determined, and what is its role?

LevelThe property is automatically determined by the hierarchical relationship of the title tags in the article.<h1>Corresponding to Level 1,<h2>Corresponding to Level 2, and so on. ThisLevelThe attribute is very useful in the style design of the catalog.You can use it to set different indents, font sizes, or colors for titles at different levels, thereby clearly displaying the logical structure and hierarchy of the article visually, enhancing the readability of the table of contents.