remark-autolink-headings

remark plugin to automatically add links to headings.

This package integrates with remark-html (or alternatives). It is better to work with rehype, which is specifically made for HTML, and to use rehype-autolink-headings instead of this package.

This package works with headings that have IDs. One way to add IDs to headings is by using remark-slug before this plugin.

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 before!

Install

npm:

npm install remark-autolink-headings

Use

Say we have the following markdown file, example.md:

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

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

const fs = require('fs')
const unified = require('unified')
const markdown = require('remark-parse')
const html = require('remark-html')
const slug = require('remark-slug')
const headings = require('remark-autolink-headings')

const doc = unified()
  .use(markdown)
  .use(slug)
  // Note that this module must be included after `remark-slug`.
  .use(headings)
  .use(html)
  .processSync(fs.readFileSync('example.md'))
  .toString()

console.log(doc)

Now, running node example yields:

<h1 id="lorem-ipsum-"><a href="#lorem-ipsum-" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Lorem ipsum 😪</h1>
<h2 id="dolorsitamet"><a href="#dolorsitamet" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>dolor—sit—amet</h2>
<h3 id="consectetur--adipisicing"><a href="#consectetur--adipisicing" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>consectetur &#x26; adipisicing</h3>
<h4 id="elit"><a href="#elit" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>elit</h4>
<h5 id="elit-1"><a href="#elit-1" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>elit</h5>

API

`remark().use(autolinkHeadings[, options])`

Automatically add links to headings.

`options`

`options.behavior`

How to create links (string, default: 'prepend').

'prepend' — inject link before the heading text
'append' — inject link after the heading text
'wrap' — wrap the whole heading text with the link
'before' — insert link before the heading
'after' — insert link after the heading

Supplying wrap will ignore any value defined by the content option. Supplying prepend, append, or wrap will ignore the group option.

`options.linkProperties`

Extra properties to set on the link (Object?). Defaults to {ariaHidden: 'true', tabIndex: -1} when in 'prepend' or 'append' mode.

`options.content`

hast nodes to insert in the link (Function|Node|Children). By default, the following is used:

{
  type: 'element',
  tagName: 'span',
  properties: {className: ['icon', 'icon-link']}
}

If behavior is wrap, then content is ignored.

If content is a function, it’s called with the current heading (Node) and should return one or more nodes:

const toString = require('mdast-util-to-string')
const h = require('hastscript')

// …

function content(node) {
  return [
    h('span.visually-hidden', 'Read the “', toString(node), '” section'),
    h('span.icon.icon-link', {ariaHidden: 'true'})
  ]
}

`options.group`

hast node to wrap the heading and link with (Function|Node), if behavior is before or after. There is no default.

If behavior is prepend, append, or wrap, then group is ignored.

If group is a function, it’s called with the current heading (Node) and should return a hast node.

const h = require('hastscript')

// …

function group(node) {
  return h('div.heading-' + node.depth + '-group')
}

Security

Use of remark-autolink-headings can open you up to a cross-site scripting (XSS) attack if you pass user provided content in linkProperties or content.

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

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.

cschweda / remark-autolink-headings Goto Github PK