@gerhobbelt/markdown-it-github-headings

    2.0.0-2 • Public • Published

    markdown-it-github-headings

    Add GitHub style anchor tags to headers

    npm travis

    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:

    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

    Install

    npm i @gerhobbelt/markdown-it-github-headings

    DownloadsWeekly Downloads

    17

    Version

    2.0.0-2

    License

    ISC

    Unpacked Size

    56.7 kB

    Total Files

    15

    Last publish

    Collaborators

    • avatar