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:
(C1)
Invalidates your HTML at Nu Html Checker. Using those plugins you will inject the "ERROR: Nop
element in scope but ap
end tag seen." to your page.(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:
(D1)
, the approach is very obscure:(i)
cloning the argumentmd
intomd2
, using it to renderheading_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 tomd2
parse and get the tokens back? Really? I feel it's a bit hard to maintain code like that.(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:
- Filter the heading tokens
- Use 'em to build an AST
- 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.