toc Plugin

Overview

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:

Copynpm 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:

Copyimport { ScullyConfig, setPluginConfig } from '@scullyio/scully';
import { getTocPlugin, TocConfig } = from './scully-plugins/toc';

const tocOptions: TocConfig = {
  blogAreaSelector: '.blog-content',
  insertSelector: '#toc',
  level: ['h2', 'h3'],
};
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 a HTML element with the id toc and insert the TOC at this place generated for headings <h2> and <h3>.

Copy# 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 webpage. 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).