Table of contents (TOC) for markdown-it markdown parser with focus on semantic and security.
npm install markdown-it-toc-done-rightA table of contents (TOC) plugin for Markdown-it with focus on semantic and security. Made to work gracefully with markdown-it-anchor.
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 will be there. Click here for additional information.
``sh`
$ npm i -S markdown-it-toc-done-right markdown-it-anchor
`js
// 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!");
`
You may specify options when using the plugin:
`js`
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\\}|\\[\\[?_?toc_?\\]?\\])"slugify | A custom slugification function | See index.js | Index to start with when making duplicate slugs unique. | 1containerClass | The class for the container DIV | "table-of-contents"containerId | The ID for the container DIV | undefined | The class for the listType HTMLElement | undefined | The class for the LI | undefined | The class for the A | undefined | Minimum level to apply anchors on or array of selected levels | 1listType | Type of list (ul for unordered, ol for ordered) | ol | A function for formatting headings (see below) | undefined | 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 :
`js${htmlencode(x)}
function format(x, htmlencode) {
return ;`
}
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:
`sh`
$ npm i -S string
`js
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 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:
`sh`
$ npm i -S uslug
`js
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 } );
`
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.(C2)
- semantic , means the that the algorithm delivers meaningful output (_id est_ more than presentation driven HTML).(C3)
- security , 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.(C2)
1. Throw HTML5 semantics away. One of the reasons for the tag
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
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) ✓.
The idea behind the plugin is incredibly simple:
1. Filter the heading tokens
1. Use 'em to build an AST
1. Apply the HTML semantics in the AST.
Very straightforward, it's one of the smallest plugins you will find around. +1 for maintenance.
Really? You reached here? You deserve a dessert! Try applying this CSS to your markdown-it-toc-done-right page.
`css
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
Want to know more about nested counters? Visit
* ⇄ 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.