Markdown-it-toc-and-anchor-with-slugid NPM

markdown-it-toc-and-anchor

markdown-it plugin to add toc and anchor links slugified id in headings

Installation

$ npm install markdown-it-toc-and-anchor-with-slugid

Usage

ES6

import markdownIt from "markdown-it"
import markdownItTocAndAnchor from "markdown-it-toc-and-anchor-with-slugid"
import uslug from 'uslug';

markdownIt({
    html: true,
    linkify: true,
    typography: true,
  })
    .use(markdownItTocAndAnchor, {
      // ...options

      // you can specify custom slugify function
      slugify: (header) => {
        return encodeURIComponent(uslug(header));
      }
    })
    .render(md)

ES5 / CommonJS

var markdownIt = require('markdown-it'),
    markdownItTocAndAnchor = require('markdown-it-toc-and-anchor-with-slugid').default;

markdownIt({
    html: true,
    linkify: true,
    typography: true,
  })
    .use(markdownItTocAndAnchor, {
      // ...options
    })
    .render(md)

:information_source: Note that the 'default' property has to be used when requiring this plugin, this is due to the use of Babel 6 now making ES6 compliant exports (Misunderstanding ES6 Modules, Upgrading Babel, Tears, and a Solution )

Options

`toc`

(default: true)

Allows you to enable/disable the toc transformation of @[toc]

`tocClassName`

(default: "markdownIt-TOC")

Option to customize html class of the <ul> wrapping the toc

`tocFirstLevel`

(default: 1)

Allows you to skip some heading level. Example: use 2 if you want to skip <h1> from the TOC.

`tocLastLevel`

(default: 6)

Allows you to skip some heading level. Example: use 5 if you want to skip <h6> from the TOC.

`tocCallback`

(default: null)

Allows you to get toc contents externally by executing a callback function returning toc elements, in addition / instead of using @toc tag in content. Example :

  markdownIt({
    html: true,
    linkify: true,
    typography: true,
  })
    .use(markdownItTocAndAnchor, {
      tocCallback: function(tocMarkdown, tocArray, tocHtml) {
        console.log(tocHtml)
      }
    })
    .render(md)

To allow callback to be more flexible, this option is also available in global markdown-it options, and in render environment. Example :

Callback in global markdown-it options

  var mdIt = markdownIt({
    html: true,
    linkify: true,
    typography: true,
  })
    .use(markdownItTocAndAnchor)

  ....

  mdIt.set({
    tocCallback: function(tocMarkdown, tocArray, tocHtml) {
      console.log(tocHtml)
    }
  })
    .render(md)

Callback in render environment

  var mdIt = markdownIt({
    html: true,
    linkify: true,
    typography: true,
  })
    .use(markdownItTocAndAnchor)

  ....

  mdIt
    .render(md, {
      tocCallback: function(tocMarkdown, tocArray, tocHtml) {
        console.log(tocHtml)
      }
    })

`anchorLink`

(default: true)

Allows you to enable/disable the anchor link in the headings

`anchorLinkSymbol`

(default: "#")

Allows you to customize the anchor link symbol

`anchorLinkSpace`

(default: true)

Allows you to enable/disable inserting a space between the anchor link and heading.

`anchorLinkSymbolClassName`

(default: null)

Allows you to customize the anchor link symbol class name. If not null, symbol will be rendered as <span class="anchorLinkSymbolClassName">anchorLinkSymbol</span>.