README

Statamic ToC

为 Statamic Bard 或 Markdown 字段或其他 HTML 内容生成自动目录

这个插件可以为 Statamic 中的任何 Bard 或 Markdown 字段生成目录（ToC）。就像任何 Antlers 标签一样，您可以在模板中使用这个插件并利用 Statamic 的魔法糖

<div class="max-w-md mx-auto">
  <div class="text-2xl font-bold">Table Of Contents</div>
  <div class="py-4 text-base text-gray-700 sm:text-lg">
    <ol class="list-decimal list-inside space-y-2">
      {{ toc depth="3" }}
      <li>
        <a class="font-bold text-cyan-800" href="#{{ toc_id }}"
          >{{ toc_title }}</a
        >
        {{ if children }}
        <ol>
          {{ *recursive children* }}
        </ol>
        {{ /if }}
      </li>
      {{ /toc }}
    </ol>
  </div>
</div>

不是很好吗？

安装

通过 composer 安装

composer require goldnead/statamic-toc

不需要进一步发布或配置文件。

用法

此插件提供了自动从您的 bard 或 markdown 字段生成数组的heading的功能，您可以在 Antlers 模板中迭代它。此外，它还附带了一个修改器，可以自动为锚点链接生成 ID。

蓝图设置

理想情况下，此插件与任何 bard 设置一起使用。在幕后，它解析给定内容中的标题并生成一个关联的嵌套数组（或非嵌套数组，具体取决于选项），您可以通过迭代它。因此，不需要特殊的标题集，只需使用普通的默认 Bard 字段即可

title: test
sections:
  main:
    display: Main
    fields:
      ...
      -
        handle: bard
        field:
          always_show_set_button: false
          buttons:
            - h2
            - h3
            - bold
            - italic
            - unorderedlist
            - orderedlist
            - removeformat
            - quote
            - anchor
            - image
            - table
          toolbar_mode: fixed
          link_noopener: false
          link_noreferrer: false
          target_blank: false
          reading_time: false
          fullscreen: true
          allow_source: true
          enable_input_rules: true
          enable_paste_rules: true
          display: Bard
          type: bard
          icon: bard
          listable: hidden

当然，您可以使用尽可能多的标题按钮。如果您更喜欢将 bard 内容保存为 HTML，可以在 bard 设置中安全地打开 save_html: true。您也可以使用此插件与您的 markdown 字段一起使用。只需像这样传递给标签即可

{{ toc content="{markdown}" }}
  ...
{{ /toc }}

或

{{ toc field="{markdown_fieldname}" }}
  ...
{{ /toc }}

《toc》修改器

在模板中使用修改器来为您的标题添加 ID

{{ text | toc }}

然后您会得到类似这样的东西

<h2 id="this-is-an-example-heading">This is an example heading</h2>
<p>
  Voluptate do ad anim do mollit proident incididunt culpa ex quis aliquip et
  irure Lorem. Voluptate enim cillum do nostrud eiusmod deserunt.
</p>

!> 注意：当标题重复时，ID 会后缀一个数字，以防止生成重复的 ID，这在 HTML 中可能会导致语义错误。

《toc》标签

您可以使用 toc-标签，就像在 Antler 模板中使用任何递归标签（如 nav 标签）一样

<ol>
  {{ toc }}
  <li>
    <a href="#{{ toc_id }}">{{ toc_title }}</a>

    {{ if children }}
    <ol>
      {{ *recursive children* }}
    </ol>
    {{ /if }}
  </li>
  {{ /toc }}
</ol>

默认情况下，此插件假定您的 bard 内容位于名为 article 的内容字段中。要更改此行为，您可以使用参数 field 指定 bard 字段的名称

{{ toc field="bard" }}

或另一种选择，您可以直接传递 bard 内容到 content 参数

{{ toc :content="bard" }} 或 {{ toc content="{bard}" }}

如果您不想将 ToC 显示为嵌套列表，可以传递参数 is_flat，它将您的列表扁平化到一级

<ol>
  {{ toc is_flat="true" }}
  <li>
    <a href="#{{ toc_id }}">{{ toc_title }}</a>
  </li>
  {{ /toc }}
</ol>

变量

每个项目都提供以下变量供您使用

此外，在 toc 标签内部存在以下全局变量

参数

您可以使用以下标签参数控制行为

许可证

这是一款商业软件。要在生产中使用它，您需要在 Statamic-Marketplace 购买许可证。