markdown-it-github-headings

Add GitHub style anchor tags to headers

Install

npm install markdown-it-github-headings

Usage

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

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:

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

carvinlo / markdown-it-github-headings Goto Github PK