markdown-it-github-headings

Add GitHub style anchor tags to headers

Install

npm install --save @gerhobbelt/markdown-it-github-headings

Usage

var md = require('@gerhobbelt/markdown-it')()
  .use(require('@gerhobbelt/markdown-it-github-headings'), options)

md.render('# hello')

Options and Defaults

The defaults will make the heading anchors behave as close to how GitHub behaves as possible.

Name | Description | Default ------------------|----------------------------------------------------------------|----------------------------------- className | name of the class that will be added to the anchor tag | anchor prefixHeadingIds | add a prefix to each heading ID. (see security note below) | true prefix | if prefixHeadingIds is true, use this string to prefix each ID. | user-content- enableHeadingLinkIcons | Adds the icon next to each heading | true linkIcon | If enableHeadingLinkIcons is true, use this to supply a custom icon (or anything really) | resetSlugger | reset the slugger counter between .render calls for duplicate headers. (See tests for example) | true

Why should I prefix heading IDs?

When using user generated content, its possible to run into DOM Clobbering when heading IDs are generated. Since IDs are used by JavaScript and CSS, a user could craft a page that breaks functionality or styles. A good way to avoid clobbering is to add a prefix to every generated ID to ensure they cannot overlap with existing IDs.

If you have full control over the content, there is less of a risk, but be aware that strange bugs related to DOM Clobbering are still possible!

For more information, here are some good resources on the topic:

• User-generated content and DOM clobbering
• In the DOM, no one will hear you scream
• A discussion about GitHub implementation
• An open issue on markdown-it repo

But the prefixes make links look real gross.

One solution is to write some client side JavaScript to force non-prefixed hashes to jump to prefixed anchors. This is how its handled on GitHub and npmjs.com.

Check out marky-deep-links for an example (works great with browserify or webpack).

Contributing

Contributions welcome! Please read the contributing guidelines first.

License

ISC