README

This plugin generates a table of contents from HTML headers in text. Anchor links in table direct to corresponding headers in text.

Table of contents can be nested - nesting level will be based on header level.

Here's screenshot of example table of contents generated by plugin:

Requirements

This plugin requires Craft CMS 3.0.0-beta.23 or later.

It also requires Anchors plugin, since it makes use of its internal functions.

Installation

You can install this plugin from the Plugin Store or with Composer.

To install plugin with composer, run following command:

composer require craftsnippets/table-of-contents

Then in the control panel go to settings, plugins - and click "install" next to "table of contents".

Usage

To create the table of contents, you need to pass HTML containing headers to craft.toc.getLinks function and output returned data using {% nav %} Twig tag.

Don't forget to also put your HTML through anhors filter provided by Anchors plugin - it will add id attribute to headers, so anchor links inside the table of contents have something to direct to.

Remember to use anchors filter after passing HTML to getLinks function. Otherwise, links in table of contents would contain escaped HTML content of links that were added to headers by Anchors plugin.

{% set text %}
some text with headers...
{% endset %}

{% set table = craft.toc.getLinks(text) %}

 <ul>
    {% nav link in table %}
        <li>
            <a href="{{ link.hash }}">{{ link.text }}</a>
            {% ifchildren %}
                <ul>
                    {% children %}
                </ul>
            {% endifchildren %}
        </li>
    {% endnav %}
</ul>

{{text|anchors}}

Don't forget to give each of your links bit of left margin to show their hierarchy.

li{
  margin-left: 1rem;
}

Nested numeric list

To display numeric count before links within the table of contents, you can use bit of CSS. This will work also for nested lists.

ul {
  counter-reset: section;               
  list-style-type: none;
}
li::before {
  counter-increment: section;            
  content: counters(section, ".") " "; 
}

Alternative header tags

By default, Table of contents plugin searches for h1, h2 and h3 tags. Just like in Anchors plugin, this can be overwritten by passing the second argument to getLinks function.

{% table = craft.toc.getLinks(text, 'header1,header2,header3') %}

Don't forget to do the same when using anchors filter.

non-ASCII characters mapping

The third parameter of getLinks() method can be used to change non-ASCII character used to generate link hashes, just like with the anchors plugin. Here's a quote from anchors plugin documentation:

The anchors filter will convert any non-ASCII characters to ASCII, using the current site’s language’s ASCII character mappings by default. If you are displaying content in a different language than the current site, use the language argument to override which ASCII character mappings should be used.

Here's the example usage:

{% set tableOfContents = craft.toc.getLinks(html, 'h1,h2,h3', entry.site.language) %}

Stripping tags from links text

If headers which are converted to links contain some html tags inside them, links within table of contents will contain these tags too. You can disable this by setting fourth parameter of getLinks() method to true.

{% set tableOfContents = craft.toc.getLinks(html, 'h1,h2,h3', null, true) %}

Smooth scrolling

You can achieve smooth scrolling effect with single CSS property.

html{
   scroll-behavior: smooth;
}

Unfortunetly it does not wok on Safari or IE - see more on caniuse.

Same effect that works in all modern browsers can be achieved with this jQuery code:

  $('.table-of-contents a').on('click', function(event) {
    var hash = '#' + $(this).attr('href').split('#')[1]
    var element = $(hash)
    if (element.length) {
      event.preventDefault();
      history.pushState(hash, undefined, hash)
      $('html, body').animate({scrollTop: element.offset().top}, 500)
    }
  });   

  window.addEventListener('popstate', function(e) {
    if(e.state && e.state.startsWith('#') && $(e.state).length){
      $('html, body').animate({scrollTop: $(e.state).offset().top}, 500)
    }
  });

  $('html, body').on("scroll mousedown wheel DOMMouseScroll mousewheel keyup touchmove", function(){
    $('html, body').stop();
  });

If a user start to scroll (using mouse scroll wheel) during an animation, scrolling will be canceled to avoid "fighting" with it.

Despite animation replacing click event, hash will still be appended to URL and browser back or forward buttons will work - thanks to use of JavaScript history API.

Icon made by Dave Gandy from www.flaticon.com.

Brought to you by Piotr Pogorzelski

craftsnippets / table-of-contents

Maintainers

Details