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

    7.0.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

    This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

    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 module, example.js, looks as follows:

    import fs from 'node:fs'
    import {unified} from 'unified'
    import remarkParse from 'remark-parse'
    import remarkSlug from 'remark-slug'
    import remarkRehype from 'remark-rehype'
    import rehypeStringify from 'rehype-stringify'
    
    const buf = fs.readFileSync('example.md')
    
    unified()
      .use(remarkParse)
      .use(remarkSlug)
      .use(remarkRehype)
      .use(rehypeStringify)
      .process(buf)
      .then((file) => {
        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

    This package exports no identifiers. The default export is remarkSlug.

    unified().use(remarkSlug)

    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

    Install

    npm i remark-slug

    DownloadsWeekly Downloads

    1,871,072

    Version

    7.0.0

    License

    MIT

    Unpacked Size

    9.57 kB

    Total Files

    5

    Last publish

    Collaborators

    • johno
    • wooorm