README

Toc

Auto-Generated Table Of Contents from Markdown Fields for Statamic 3.

This generates a Table Of Contents from a Markdown field.

A list of Headings is saved in the entry as html and can either be rendered directly using {{ table_of_contents }} or through the provided tag {{ toc }} with a customizable wrapper view.

Installation

Require it using Composer.

composer require jedamzik/statamic-toc

Set up a Collection

Publish the wrapper view and package configuration from Njed\Toc\ServiceProvider:

php artisan vendor:publish

Provide a collection handle and a field handle in config/toc.php to activate Toc for a given collection:

return [
    'collections' => [
        'posts' => 'content'
    ],
    ...
];

Heading Depth

By default only h1 and h2 are used for the Table of Contents. If you want to include further heading levels, add them to the config:

return [
    ...
    'includeLevels' => [3, 4]
];

List items for all headings with a level > 2 will have a .child class added so you can style them separately.

Anchor Links for Headings

Items in the Table of Contents can function as anchor links to the heading fragment:

return [
    ...
    'anchorLinks' => true
];

Linked page fragments are a slugified version of the Heading string (Example Title -> #example-title).

You can extend your Markdown Parser with the provided Njed\Toc\Extensions\CommonMark\TitleAnchorIdExtension to provide these ids for your heading nodes in your rendered views.

To extend the default Parser for all Markdown fields in your Statamic instance, add it to your boot method in the AppServiceProvider:

Markdown::addExtension(function () {
    return new \Njed\Toc\Extensions\CommonMark\TitleAnchorIdExtension;
});

To only use this Extension on a specific Markdown field, you can create a new Parser and specify it for your Markdown field.

Markdown::extend('special', function ($parser) {
    return $parser
        ->withStatamicDefaults()
        ->addExtension(function () {
            return new \Njed\Toc\Extensions\CommonMark\TitleAnchorIdExtension;
        });
});

You can set a custom parser for markdown fields either in the control panel or through the parser attribute in your blueprint file:

-
    handle: content
    field:
        ...
        type: markdown
        parser: special

Changelog

Please see CHANGELOG for more information what has changed recently.

License

The MIT License (MIT). Please see License File for more information.