remark-slug
    TypeScript icon, indicating that this package has built-in type declarations

    6.1.0 • Public • Published

    remark-slug

    Build Coverage Downloads Size Sponsors Backers Chat

    remark plugin to add anchors headings using GitHub’s algorithm.

    ⚠️ Note: This is often useful when compiling to HTML. If you’re doing that, it’s probably smarter to use remark-rehype and rehype-slug and benefit from the rehype ecosystem.

    Note!

    This plugin is ready for the new parser in remark (remarkjs/remark#536). No change is needed: it works exactly the same now as it did previously!

    Install

    npm:

    npm install remark-slug

    Use

    Say we have the following file, example.md:

    # Lorem ipsum 😪
    
    ## dolor—sit—amet
    
    ### consectetur & adipisicing
    
    #### elit
    
    ##### elit

    And our script, example.js, looks as follows:

    var fs = require('fs')
    var unified = require('unified')
    var markdown = require('remark-parse')
    var slug = require('remark-slug')
    var remark2rehype = require('remark-rehype')
    var html = require('rehype-stringify')
    
    unified()
      .use(markdown)
      .use(slug)
      .use(remark2rehype)
      .use(html)
      .process(fs.readFileSync('example.md'), function(err, file) {
        if (err) throw err
        console.log(String(file))
      })

    Now, running node example yields:

    <h1 id="lorem-ipsum-">Lorem ipsum 😪</h1>
    <h2 id="dolorsitamet">dolor—sit—amet</h2>
    <h3 id="consectetur--adipisicing">consectetur &#x26; adipisicing</h3>
    <h4 id="elit">elit</h4>
    <h5 id="elit-1">elit</h5>

    API

    remark().use(slug)

    Add anchors headings using GitHub’s algorithm.

    Uses github-slugger to creates GitHub-style slugs.

    Sets data.id and data.hProperties.id on headings. The first can be used by any plugin as a unique identifier, the second tells mdast-util-to-hast (used in remark-html and remark-rehype) to use its value as an id attribute.

    Security

    Use of remark-slug can open you up to a cross-site scripting (XSS) attack as it sets id attributes on headings. In a browser, elements are retrievable by id with JavaScript and CSS. If a user injects a heading that slugs to an id you are already using, the user content may impersonate the website.

    Always be wary with user input and use rehype-sanitize.

    Related

    Contribute

    See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

    This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

    License

    MIT © Titus Wormer

    Keywords

    none

    Install

    npm i [email protected]

    Version

    6.1.0

    License

    MIT

    Unpacked Size

    8.8 kB

    Total Files

    5

    Last publish

    Collaborators

    • johno
    • wooorm