在使用安企CMS管理网站内容时，如何有效地组织长篇文章的结构，提升读者的阅读体验，是一个值得关注的问题。自动生成文章目录（Table of Contents, 简称TOC）就是一种非常实用的解决方案。它不仅能让读者快速了解文章大纲，还能方便他们跳转到感兴趣的部分，同时也有助于搜索引擎更好地理解文章结构。

安企CMS在内容管理方面提供了对Markdown语法的支持，并巧妙地利用了这一特性，允许我们从Markdown编写的内容中提取出标题层级信息，进而生成可导航的文章目录。这意味着只要你在编辑文章时合理地使用了Markdown的标题（#、##、###等），系统就能帮助我们构建这份目录。

开启Markdown编辑器：前置准备

在着手生成目录之前，我们需要确保Markdown编辑器功能已经在安企CMS后台开启。这个设置通常可以在“后台->全局设置->内容设置”中找到。开启后，你所编辑的文章内容才能被系统识别为Markdown格式，并进行后续的解析。

核心机制：AnQiCMS如何解析Markdown内容

安企CMS的强大之处在于其模板引擎对Markdown内容的深度解析能力。当你使用Markdown语法编写文章，例如：

# 这是一个一级标题
## 这是二级标题
### 这是三级标题

系统在渲染文章时，不仅会将这些Markdown标题转换为对应的HTML标签（<h1>、<h2>、<h3>），还会提取出这些标题的元数据。这些元数据通过archiveDetail标签中的ContentTitles字段暴露给模板，它是一个数组对象，包含了每个标题的文本、HTML标签类型（如h1, h2）、层级以及可能的自定义前缀。正是这个ContentTitles数组，为我们自动生成目录提供了基础数据。

在模板中构建文章目录（TOC）

要将这些提取出的标题信息展示为可点击的文章目录，我们需要在相应的模板文件中进行操作，通常是在文章详情页的模板（如{模型table}/detail.html）中进行。

首先，通过archiveDetail标签获取文章的ContentTitles数据：

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

如果contentTitles数组不为空，说明文章中存在标题，此时我们就可以开始构建目录结构了。下面是一个简单的代码示例，展示如何遍历ContentTitles并生成一个基础的目录：

{% archiveDetail contentTitles with name="ContentTitles" %}
{% if contentTitles %}
<nav class="article-toc">
    <h3>文章目录</h3>
    <ul>
        {% for item in contentTitles %}
        <li class="toc-level-{{ item.Level }}">
            <a href="#{{ item.Title|urlencode|lower|replace:" ","-" }}" title="{{ item.Title }}">
                {% if item.Prefix %}{{ item.Prefix }} {% endif %}{{ item.Title }}
            </a>
        </li>
        {% endfor %}
    </ul>
</nav>
{% endif %}

让我们来解释一下这段代码：

  1. {% archiveDetail contentTitles with name="ContentTitles" %}: 这行代码从当前文章的详细信息中获取所有标题的列表，并将其赋值给contentTitles变量。
  2. {% if contentTitles %}: 判断文章是否存在标题，如果存在才渲染目录，避免空目录的出现。
  3. <nav class="article-toc">...</nav>: 这是一个语义化的HTML标签，用于包裹文章目录，方便通过CSS进行样式控制。
  4. {% for item in contentTitles %}: 遍历contentTitles数组中的每一个标题项。
  5. <li class="toc-level-{{ item.Level }}">: 为每个目录项生成一个列表项，并根据item.Level（标题层级，如1代表h1，2代表h2）添加不同的CSS类，这有助于我们通过样式表控制目录的缩进和外观，使其更具层级感。
  6. <a href="#{{ item.Title|urlencode|lower|replace:" ","-" }}" title="{{ item.Title }}">: 这是目录项的核心部分，创建一个超链接。
    • href="#...": 链接的目标是页内锚点。我们假设安企CMS的Markdown解析器在将Markdown标题转换为HTML时，会自动为h标签添加一个基于标题文本的ID（例如## My Heading会被渲染为<h2 id="my-heading">My Heading</h2>）。
    • item.Title|urlencode|lower|replace:" ","-": 为了确保生成的锚点ID是有效的，我们对item.Title进行了几个处理：
      • urlencode: 将标题中的特殊字符进行URL编码，避免造成链接错误。
      • lower: 将标题转换为小写。
      • replace:" ","-": 将标题中的空格替换为连字符-，这是一种常见的URL slug和锚点ID的生成方式。
    • title="{{ item.Title }}": 添加title属性，提供鼠标悬停时的提示信息。
  7. {% if item.Prefix %}{{ item.Prefix }} {% endif %}{{ item.Title }}: 显示标题的文本内容。item.Prefix是可选的，如果存在则显示。

样式调整建议：

为了让文章目录在页面上美观且易于使用，你可以通过CSS对.article-toc和.toc-level-X等类进行样式定义，例如设置边框、背景色、字体大小、缩进等，使其与网站整体设计风格保持一致。

/* 示例 CSS 样式 */
.article-toc {
    border: 1px solid #eee;
    padding: 15px;
    margin-bottom: 20px;
    background-color: #f9f9f9;
}
.article-toc h3 {
    font-size: 18px;
    margin-top: 0;
    margin-bottom: 10px;
    color: #333;
}
.article-toc ul {
    list-style: none;
    padding-left: 0;
}
.article-toc ul li {
    line-height: 1.8;
}
/* 不同层级标题的缩进 */
.toc-level-1 { padding-left: 0; font-weight: bold; }
.toc-level-2 { padding-left: 15px; }
.toc-level-3 { padding-left: 30px; }
.toc-level-4 { padding-left: 45px; }
/* ...更多层级 */

实践技巧与注意事项

  • Markdown标题的规范使用：确保文章作者在编写内容时，始终遵循Markdown标题的语义化使用，即一级标题用于文章主旨，二级、三级标题用于章节划分，层级清晰。
  • 目录位置的选择：文章目录通常放置在文章内容的开头部分，或者侧边栏，以便读者一眼就能看到。你可以通过include标签将这段目录代码嵌入到文章详情模板的合适位置。
  • 兼容性：上述方法依赖于安企CMS内置的Markdown解析器能够自动为生成的HTML标题添加可预测的ID属性。如果遇到目录链接点击后无法跳转的问题，可能需要检查Markdown渲染器是否提供了