rehype-autolink-headings

What is rehype-autolink-headings?

The rehype-autolink-headings package is a plugin for the rehype ecosystem that automatically adds links to headings in HTML documents. This is particularly useful for generating anchor links for headings in markdown files that are converted to HTML, making it easier to navigate through long documents.

What are rehype-autolink-headings's main functionalities?

Basic Usage

This code demonstrates the basic usage of rehype-autolink-headings. It processes an HTML string containing headings and automatically adds anchor links to those headings.

const rehype = require('rehype');
const rehypeAutolinkHeadings = require('rehype-autolink-headings');

rehype()
  .use(rehypeAutolinkHeadings)
  .process('<h1>Title</h1><h2>Subtitle</h2>', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Customizing Link Properties

This example shows how to customize the behavior of the links added to the headings. The 'behavior' option is set to 'wrap', which wraps the heading text with the anchor link.

const rehype = require('rehype');
const rehypeAutolinkHeadings = require('rehype-autolink-headings');

rehype()
  .use(rehypeAutolinkHeadings, { behavior: 'wrap' })
  .process('<h1>Title</h1><h2>Subtitle</h2>', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Adding Custom Properties to Links

This example demonstrates how to add custom properties to the generated links. Here, a custom class name 'custom-class' is added to the anchor links.

const rehype = require('rehype');
const rehypeAutolinkHeadings = require('rehype-autolink-headings');

rehype()
  .use(rehypeAutolinkHeadings, { properties: { className: 'custom-class' } })
  .process('<h1>Title</h1><h2>Subtitle</h2>', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Other packages similar to rehype-autolink-headings

remark-autolink-headings

remark-autolink-headings is a plugin for the remark ecosystem that adds links to headings in markdown documents. It is similar to rehype-autolink-headings but is used within the remark ecosystem, which is focused on processing markdown rather than HTML.

markdown-it-anchor

markdown-it-anchor is a plugin for the markdown-it parser that automatically adds anchor links to headings in markdown documents. It provides similar functionality to rehype-autolink-headings but is designed to work with the markdown-it parser.

gatsby-remark-autolink-headers

gatsby-remark-autolink-headers is a Gatsby plugin that adds anchor links to headings in markdown files processed by Gatsby. It is similar to rehype-autolink-headings but is specifically designed for use within the Gatsby framework.

README

rehype-autolink-headings

rehype plugin to automatically add links to headings (h1-h6).

Install

npm:

npm install rehype-autolink-headings

Use

Say we have the following file, fragment.html:

<h1>Lorem ipsum 😪</h1>
<h2>dolor—sit—amet</h2>
<h3>consectetur &amp; adipisicing</h3>
<h4>elit</h4>
<h5>elit</h5>

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

var fs = require('fs')
var rehype = require('rehype')
var slug = require('rehype-slug')
var link = require('rehype-autolink-headings')

var doc = fs.readFileSync('fragment.html')

rehype()
  .data('settings', {fragment: true})
  .use(slug)
  .use(link)
  .process(doc, function(err, file) {
    if (err) throw err
    console.log(String(file))
  })

Now, running node example yields:

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

API

rehype().use(link[, options])

Add links to headings (h1-h6) with an id.

options

options.behavior

How to add a link (string, default: prepend). Can be:

• 'prepend' and 'append' — insert a link with content in it respectively before or after the heading contents
• 'wrap' — wrap a link around the current heading contents

options.properties

Properties for the added link (Object, default: {} if 'wrap', {ariaHidden: true} otherwise).

options.content

Content to add in link (Node or Array.<Node>, default: a span element with icon and icon-link classes). Ignored if 'wrap'.

Related

• rehype-slug

Contribute

See contributing.md in rehypejs/.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, organisation, or community you agree to abide by its terms.

License

MIT © Titus Wormer