scully-plugin-toc
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.0 • Public • Published

    scully-plugin-toc - The Table Of Contents postRenderer

    Build Status npm Dependency Status devDependency Status

    npm PRs Welcome Open Source Love

    Conventional Commits Commitizen friendly semantic-release

    This plugin for Scully provides a postRenderer to generate a table of contents (TOC) for the rendered route content.

    Installation

    To install this library with npm run:

    npm i scully-plugin-toc --save-dev

    Usage

    To use the plugin you should import it in your Scully configuration file (scully.<project-name>.config.ts) and define it as a postRenderer for a route definition. You can configure the plugin by using the toc options:

    import { ScullyConfig, setPluginConfig } from '@scullyio/scully';
    import { getTocPlugin, TocConfig } = from './scully-plugins/toc';
    
    const tocOptions: TocConfig = {
      blogAreaSelector: '.blog-content', // where to search for TOC headings
      insertSelector: '#toc', // where to insert the TOC
      level: ['h2', 'h3'], // what heading levels to include
      trailingSlash: true, // add trailing slash before the anker ('#')
      scrollIntoViewOnClick: true  // add event to each link that scrolls into view on click:
                                   // onclick="document.getElementById('target-id').scrollIntoView()"
    };
    const TocPlugin = getTocPlugin();
    setPluginConfig(TocPlugin, tocOptions);
    
    export const config: ScullyConfig = {
      projectRoot: './src',
      projectName: 'your-project-name',
      outDir: './dist/static',
      routes: {
        '/blog/:slug': {
          type: 'contentFolder',
          postRenderers: ['toc'],
          slug: {
            folder: './blog',
          },
        },
      },
    };

    The TOC is generated by analyzing the headings (<h1>, <h2>, etc.) generated by Scully. The above example configuration will look for an HTML element with the id toc and insert the TOC at this place generated for headings <h2> and <h3>.

    # my blog post
    
    <div id="toc">
      <h2>Table of contents</h2>
    </div>
    
    ## heading 1
    
    ### subheading 1
    
    ## heading 2
    
    ### subheading 2

    Options

    You can configure the scully-plugin-toc by adding the toc options to your route configuration. The following table will explain the options in detail.

    • blogAreaSelector: This defines the area in which the scully-plugin-toc will search for headings. If you use for example <div class="blog"><scully-content></scully-content></div> you should define blogAreaSelector: ".blog" to generate the TOC only from the blog content and not from the whole web page. If the parameter is not set, the plugin will search for heading at the whole page.
    • insertSelector: The selector defines the point where the scully-plugin-toc will inset the generated TOC. By default, the plugin will use #toc as selector. It will skip the TOC generation when there is no selector match. In fact to insert the TOC in a blog post, you should at least add a <div id="toc"></div> in your blog post and this is the place where the TOC will be inserted.
    • level: This option defines the heading levels to include in the TOC. By default, the value level: ['h2', 'h3'] is used. Only valid HTML headings are supported (h1, h2, h3, h4, h5 and h6).
    • trailingSlash define weather a trailing slash will be added to the generated link just before the anker reference or not. Set this to true will lead into generated links like this: .../foo/#myTocLink. If it's false (default), the generated link will look like this: .../foo#myTocLink.
    • scrollIntoViewOnClick set to true will cause that to each link a onclick event will be added that tries to scroll the target element id into the view: onclick="document.getElementById('target-id').scrollIntoView()".

    Install

    npm i scully-plugin-toc

    DownloadsWeekly Downloads

    2,727

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    108 kB

    Total Files

    23

    Last publish

    Collaborators

    • d-koppenhagen