README

从 H1...H6 标签生成目录

此包提供了一个简单、框架无关的库，用于从 HTML 标记构建目录。它通过评估您的 H1...H6 标签来实现这一点。它还可以自动向标题标签添加适当的 id 锚属性，以便页面内的链接能够正常工作。

功能

生成 HTML 菜单和 KnpMenu Item 菜单
在内容中添加锚 ID 属性到尚未存在的 H1...H6 标签
您可以指定要在目录中包含的 H1...H6 标题标签级别
包含一个用于从模板直接生成目录和兼容标记的 Twig 扩展
使用灵活的 KnpMenu 库生成菜单
PSR-0 至 PSR-2 兼容
Composer 兼容
单元测试

秉承 KISS 哲学，此库做了一些假设

您的内容层次结构完全由标题 (H1...H6) 标签定义。在生成目录时，忽略所有其他标签。
目录中的链接标题与标题标签的 title 属性匹配，如果没有 title，则与标题标签的纯文本正文匹配。

安装选项

通过在您的 composer.json 文件中包含以下内容来通过 Composer 安装

{
    "require": {
        "caseyamcl/toc": "~1.0",
    }
}

或者，将 src 文件夹放入您的应用程序中，并使用 PSR-4 自动加载器包含文件。

用法

此包包含两个基本类

TOC\MarkupFixer：向任何尚未有任何 H1...H6 标签添加 id 锚属性（您可以在运行时指定要使用的标题标签级别）
TOC\TocGenerator：从 HTML 标记生成目录

基本示例

$myHtmlContent = <<<END
    <h1>This is a header tag with no anchor id</h1>
    <p>Lorum ipsum doler sit amet</p>
    <h2 id='foo'>This is a header tag with an anchor id</h2>
    <p>Stuff here</p>
    <h3 id='bar'>This is a header tag with an anchor id</h3>
END;

$markupFixer  = new TOC\MarkupFixer();
$tocGenerator = new TOC\TocGenerator();

// This ensures that all header tags have `id` attributes so they can be used as anchor links
$htmlOut  = "<div class='content'>" . $markupFixer->fix($myHtmlContent) . "</div>";

// This generates the Table of Contents in HTML
$htmlOut .= "<div class='toc'><ul>" . $tocGenerator->getHtmlMenu($myHtmlContent) . "</ul></div>";

echo $htmlOut;

Twig 集成

此库包含一个 Twig 扩展，允许您从 Twig 模板加载 TOC 列表并向标记添加锚。

为了启用 Twig 集成，您必须将 TocTwigExtension 注册到您的 Twig 环境

$myTwig = new \Twig_Environment();
$myTwig->addExtension(new TOC\TocTwigExtension());

具体来说，该扩展添加了一个用于生成目录 HTML 的 Twig 函数

{# Generates HTML markup for given htmlContent #}
<ul>{{ toc(htmlContent) }}</ul>

它还提供了一个函数和一个过滤器，以确保您的所有内容都包含所有 HTML 标题标签的锚。它们都做同样的事情，因此请选择最适合您需求的一个

{# Adds anchor links (id tags) for given htmlContent #}
{{ add_anchors(htmlContent) }}

{# You can also use it as a filter #}
<div class='my_content'>
    {{ htmlContent | add_anchors }}
</div>

您的 HTML 内容可能已经硬编码在您的 Twig 模板中。一种简单的方法是确保内容被 {% block %}...{% endblock %} 标签包围，然后将该块传递给 toc 函数。

例如

{% extends 'base.html.twig' %}
{% block page_content %}
<div class='page_sidebar'>
   {{ toc(add_anchors(block('my_writeup'))) }}
</div>

<div class='page_content'>
   {{ add_anchors(block('my_writeup')) }}
</div>
{% endblock %}

{% block my_writeup %}
<h1>Hi There</h1>
<p>Lorum ipsum baz biz etecetra</p>
<h2>This is some content</h2>
<p>More content here.  Blah blah</p>
{% endblock %}

指定要包含的标题级别

您可以选择只包含 TOC 中的特定 h1...h6 标题级别。为此，将两个额外的参数传递给 TocGenerator::getHtmlMenu() 方法： $topLevel 和 $depth。例如

$tocGenerator = new TOC\TocGenerator();

// Get TOC using h2, h3, h4
$toc->getHtmlMenu($someHtmlContent, 2, 3);

// Get TOC using h1, h2
$toc->getHtmlMenu($someHtmlContent, 1, 2);

// Get TOC using h4, h5, h6
$toc->getHtmlMenu($someHtmlContent, 4, 3);

包中的大多数其他方法也处理这些参数

$tocGenerator = new TOC\TocGenerator();
$markupFixer = new TOC\MarkupFixer();

// Get KnpMenu using h1, h2, h3
$tocGenerator->getMenu($someHtmlContent, 1, 3);

// Fix markup for h3, h4 tags only
$markupFixer->fix($someHtmlContent, 3, 2);

Twig 函数和过滤器也接受这些参数

{# Generate TOC using h2, h3 tags #}
{{ toc(my_content, 2, 3) }}

{# Add anchors to h4, h5, h6 tags #}
{{ my_content | add_anchors(4, 3) }}

自定义菜单输出

您可以为TocGenerator类输出的列表自定义渲染方式。默认情况下，TocGenerator使用KnpMenu ListRenderer类来输出HTML。

您可以将自己的ListRenderer类的实例传递给TocGenerator::getHtmlMenu()。或者，您可以传递自己的渲染器（实现Knp\Menu\Renderer\RendererInterface）。

例如，您可能希望为列表项使用不同的CSS类

$options = [
    'currentAsLink' => false,
    'currentClass'  => 'curr_page',
    'ancestorClass' => 'curr_ancestor',
    'branch_class'  => 'branch
];

$renderer = new Knp\Menu\Renderer\ListRenderer(new Knp\Menu\Matcher\Matcher(), $options);

// Render the list
$tocGenerator = new TOC\TocGenerator();
$listHtml = $tocGenerator->getHtmlMenu($someHtmlContent, 1, 6, $renderer);

使用Twig进行自定义

KnpMenu库提供了比默认库更健壮的与Twig模板系统的集成。您可以通过使用KnpMenu捆绑的TwigRenderer来利用它

$twigLoader = new \Twig_Loader_Filesystem(array(
    __DIR__.'/vendor/KnpMenu/src/Knp/Menu/Resources/views',
    // ...paths to your own Twig templates that render KnpMenus...
));

$twig = new \Twig_Environment($twigLoader);
$itemMatcher = \Knp\Menu\Matcher\Matcher();
$menuRenderer = new \Knp\Menu\Renderer\TwigRenderer($twig, 'knp_menu.html.twig', $itemMatcher);


$tocGenerator = new TOC\TocGenerator();

// Output the Menu using the template 
echo $menuRenderer->render($tocGenerator->getMenu($someHtmlContent));

ideea / toc

维护者

详细信息