Nighttime Peanut Migrations

    @higby/eleventy-plugin-nesting-toc

    1.3.1 • Public • Published

    Table of Contents (nesting) Eleventy Plugin

    npm

    This Eleventy plugin will generate a (property nested) TOC from page content using an Eleventy filter.

    HTML:

    <h1>Hello, World</h1>
    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ad animi assumenda consequuntur debitis ea eligendi eos hic necessitatibus, odio recusandae rem similique, totam unde. Asperiores cumque facere nisi quibusdam vitae.
    
    <h2 id="greetings-from-mars">Greetings from Mars</h2>
    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Accusamus aperiam at blanditiis dolorem ea, eius impedit maxime non omnis quia repudiandae sit, suscipit vel veniam voluptas. Dignissimos eos porro sit.
    
    <h3 id="the-red-planet">The red planet</h3>
    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aut consequatur dicta doloremque est iure minima placeat recusandae sit. Dolorum quis quod sequi! Commodi cupiditate debitis, dolore error excepturi nulla optio.
    
    <h2 id="greetings-from-pluto">Greetings from Pluto</h2>

    Generated TOC:

    <nav class="toc">
    <ol>
        <li><a href="#greetings-from-mars">Greetings from Mars</a></li>
        <ol>
            <li><a href="#the-red-planet">The red planet</a></li>
        </ol>
        <li><a href="#greetings-from-pluto">Greetings from Pluto</a></li>
    </ol>
    </nav>

    This Readme

    Options

    const defaults = {
      tags: ['h2', 'h3', 'h4'],    // Which heading tags are selected (headings must each have an ID attribute)
      ignoredElements: [],         // Elements to ignore when constructing the label for every header (useful for ignoring permalinks, must be selectors)
      wrapper: 'nav',              // Element to put around the root `ol`
      wrapperClass: 'toc',         // Class for the element around the root `ol`
      headingText: '',             // Optional text to show in heading outside/ inside the wrapper element
      headingTag: 'h2',            // Heading tag when showing heading outside/ inside the wrapper element
      headingPlacement: 'outside'  // Whether the heading will be outside the wrapper or not
    }

    Install

    npm i --save eleventy-plugin-nesting-toc

    Usage

    Adding it to the Eleventy Engine

    IMPORTANT NOTE: Your heading tags will need to have ids on them, so that the TOC can provide proper anchor links to them. Eleventy does not do this for you ootb. You can use a plugin like markdown-it-anchor to add those ids to the headings automagically

    // .eleventy.js
    module.exports = function (eleventyConfig) {
      //...
    + const pluginTOC = require('eleventy-plugin-nesting-toc');
    + eleventyConfig.addPlugin(pluginTOC);
    
      // Example Markdown configuration (to add IDs to the headers)
      const markdownIt = require('markdown-it');
      const markdownItAnchor = require('markdown-it-anchor');
      eleventyConfig.setLibrary("md",
          markdownIt({
              html: true,
              linkify: true,
              typographer: true,
          }).use(markdownItAnchor, {})
      );
      //...
    }

    Using the provided filter

    <aside>
      {{ content | toc | safe }}
    </aside>
    <article>
      {{ content }}
    </article>

    Configuring

    You can override any of the options at the time that you call it, or when you add it to the eleventy engine. All the options will be merged together, with the precedence being when invoking the filter > .eleventy.js > defaults.

    Override the defaults for your whole site:

    module.exports = function (eleventyConfig) {
      //...
    + const pluginTOC = require('eleventy-plugin-nesting-toc');
    + eleventyConfig.addPlugin(pluginTOC, {tags: ['h2']});
      //...
    }

    And override those just for one template, as it's being invoked

    <aside>
      {{ content | toc(tags=['h2', 'h3'], wrapperClass='fixed toc') | safe }}
    </aside>

    If you have specific headings which you don't want to be included in the TOC, you can add the data-toc-exclude attribute to exclude these headings.

    One way to add this attribute is via the use of the markdown-it-attrs npm package.

    ### Level 3 heading to ignore {data-toc-exclude}

    Gotchyas

    A few things must be in place for this to work properly, and provide the proper nested structure

    • The first matched heading on the page should be the topmost. Don't put an h3 before an h2.
    • you can only use actual heading tags. Don't use tags=['section'], etc.

    Install

    npm i @higby/eleventy-plugin-nesting-toc

    DownloadsWeekly Downloads

    8

    Version

    1.3.1

    License

    ISC

    Unpacked Size

    16.3 kB

    Total Files

    5

    Last publish

    Collaborators

    • higby