@gerhobbelt/markdown-it-toc-done-right

markdown-it-toc-done-right

A table of contents (TOC) plugin for Markdown-it with focus on semantic and security. Made to work gracefully with markdown-it-anchor.

tl;dr

If you are drowning in table of contents plugins options, just pick this one. It delivers an accessible, semantic, SEO friendly and safe TOC. Place one of: ${toc}, [[toc]], [toc], [[_toc_]] in your markdown and, BOOM, the <nav class="table-of-contents"> will be there. Click here for additional information.

Installation

$ npm i -S markdown-it-toc-done-right markdown-it-anchor

Usage

// node.js
var md = require("markdown-it")({
	html: false,
	xhtmlOut: true,
	typographer: true
}).use( require("markdown-it-anchor"), { permalink: true, permalinkBefore: true, permalinkSymbol: '§' } )
  .use( require("markdown-it-toc-done-right") );

var result = md.render("# markdown-it rulezz!\n\n${toc}\n## with markdown-it-toc-done-right rulezz even more!");

// browser without AMD, added to "window" on script load
// Note, there is no dash in "markdownit".
var md = window.markdownit({
	html: false,
	xhtmlOut: true,
	typographer: true
}).use( window.markdownItAnchor, { permalink: true, permalinkBefore: true, permalinkSymbol: '§' } )
  .use( window.markdownItTocDoneRight );

var result = md.render("# markdown-it rulezz!\n\n${toc}\n## with markdown-it-toc-done-right rulezz even more!");

Options

You may specify options when using the plugin:

md.use(require("markdown-it-toc-done-right"), options);

These options are available:

Name	Description	Default
placeholder	The pattern serving as the TOC placeholder in your markdown	"(\$\{toc\}
slugify	A custom slugification function	See index.js
uniqueSlugStartIndex	Index to start with when making duplicate slugs unique.	1
containerClass	The class for the container DIV	"table-of-contents"
containerId	The ID for the container DIV	undefined
listClass	The class for the listType HTMLElement	undefined
itemClass	The class for the LI	undefined
linkClass	The class for the A	undefined
level	Minimum level to apply anchors on or array of selected levels	1
listType	Type of list (ul for unordered, ol for ordered)	ol
format	A function for formatting headings (see below)	undefined
callback	A function (html, ast) {} called after rendering.	undefined

format is an optional function for changing how the headings are displayed in the TOC e.g. Wrapping content in <span>:

function format(x, htmlencode) {
	return `<span>${htmlencode(x)}</span>`;
}

User-Friendly URLs

Starting from v2.0.0, markdown-it-toc-done-right dropped package string keeping it's core value of being an unopinionated and secure library. Yet, users looking for backward compatibility may want the old slugify:

$ npm i -S string

var string = require("string");

function legacySlugify(s) {
	return string(s).slugify().toString();
}

var md = require("markdown-it")({
	html: false,
	xhtmlOut: true,
	typographer: true
}).use( require("markdown-it-anchor"), { permalink: true, permalinkBefore: true, permalinkSymbol: '§', slugify: legacySlugify } )
  .use( require("markdown-it-toc-done-right"), { slugify: legacySlugify } );

Unicode support

Unicode is supported by default. Yet, if you are looking for a "prettier" --opinionated-- link, i.e without %xx, you may want to take a look at uslug:

$ npm i -S uslug

var uslug = require("uslug");

function uslugify(s) {
	return uslug(s);
}

var md = require("markdown-it")({
	html: false,
	xhtmlOut: true,
	typographer: true
}).use( require("markdown-it-anchor"), { permalink: true, permalinkBefore: true, permalinkSymbol: '§', slugify: uslugify } )
  .use( require("markdown-it-toc-done-right"), { slugify: uslugify } );

Really? Another markdown-it table of contents plugin?

Unfortunately, I'm a little rigorous developer and most of the existing plugins (exempli gratia markdown-it-toc-and-anchor, markdown-it-table-of-contents, markdown-it-toc, markdown-it-toc-x3 et cetera) fail under, at least, one of these criteria: correctness, semantic, security.

Let me first define those:

• correctness (C1), means the that the algorithm is correct with respect to a specification.
• semantic (C2), means the that the algorithm delivers meaningful output (id est more than presentation driven HTML).
• security (C3), means the that the algorithm protects you, by default, against malicious users.

Whenever I need to work with markdown syntax, I leverage Markdown-it. It's GREAT, the developers care about security, it's built for flexibility, have a huge community extending it and outputs a semantic perfect (X)HTML. Somehow, not all plugin developers keep the same high standards for their extensions. Take for example the three most popular, at the time of writing this README, solutions for this problem: markdown-it-toc-and-anchor, markdown-it-table-of-contents, markdown-it-toc. They all implement their TOC as inline and, most obscure of all, after the emphasis rule. Does it make any sense? Could someone explain why it's like that? Two errors get derived from this single choice:

1. (C1) Invalidates your HTML at Nu Html Checker. Using those plugins you will inject the "ERROR: No p element in scope but a p end tag seen." to your page.
2. (C2) Throw HTML5 semantics away. One of the reasons for the tag <nav> to exists is exactly to be used as a container for table of contents. Semantic is great for SEO and Accessibility. If you, like me, care about SEO and Accessibility you can't use those plugins.

Of course that neither of the above arguments degrades your presentation, but as a coach that trains people to be A-grade web developers to work with very sensitive data (i.e. money and credit card) it doesn't make sense for me to keep any one of these plugins. Another very common (C1) mistake that can be found in the wild is using an optional regular expression to match the placeholder in the source, but using a hard-coded charCodeAt value to reject a token. Finally, (C3) is also a concern since the prevalence of unescaped HTML is currently very high; opening your page to XSS and other HTML injection security vulnerabilities.

The only other plugin that addresses (C2) and (C3) found is markdown-it-toc-x3. It's made because the author also noted (C2) and addresses (C3) by always using markdown-it token.attrSet(k,v), but I've technical (D1) and philosophical (D2) disagreements with the code:

1. (D1), the approach is very obscure: (i) cloning the argument md into md2, using it to render heading_open next token into something that needs to be slugified, stripped and will generate more tokens to be concatenated with token.children; (ii) hard-coding <svg> into it?; (iii) building a string representation of the TOC to md2 parse and get the tokens back? Really? I feel it's a bit hard to maintain code like that.
2. (D2) composability, do one thing and do it well. If a plugin could be broken in two plugins, it should be broken. +1 for maintenance.

And those are the "why"s of markdown-it-toc-done-right. It protects you by HTML enconding critical points (C3) ✓, outputs a nice semantic tag nav which works the same as WAI-ARIA landmark role="navigation" saving you from this kind of issue (C2) ✓ and get the job done with an über simple approach (C1) ✓.

How it works?

The idea behind the plugin is incredibly simple:

1. Filter the heading tokens
2. Use 'em to build an AST
3. Apply the HTML semantics in the AST.

Very straightforward, it's one of the smallest plugins you will find around. +1 for maintenance.

Cherry on top

Really? You reached here? You deserve a dessert! Try applying this CSS to your markdown-it-toc-done-right page.

body { scroll-behavior: smooth; }

ol { counter-reset: list-item; }
li { display: block; counter-increment: list-item; }
li:before { content: counters(list-item,'.') ' '; }

Want to know more about scroll-behavior? Visit https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior.
Want to know more about nested counters? Visit https://www.w3.org/TR/css-lists-3/.

Contributing

• ⇄ Pull requests and ★ Stars are always welcome.
• For bugs and feature requests, please create an issue.
• Pull requests must be accompanied by passing automated tests ($ npm test).

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub.