remark-heading-lines

remark-heading-lines is a remark plugin which adds a link at a headline containing the start- and end-line of a headline section respecting its hierarchy. The lines refer to the source markdown file.

An exemplary usecase for this plugin is to generate wikipedia-like edit links beside headlines (see the example below).

Usage

Say we have the following file example.md:

# Level 1

paragraph

## Level 2

paragraph

### Level 3

paragraph

## Level 2

paragraph

# Level 1

paragraph

and a module example.js:

import { remark } from 'remark'
import remarkHeadingLines from 'remark-heading-lines'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import { read } from 'to-vfile'

const file = await remark()
    .use(remarkHeadingLines, {
        position: 'after',
        maxDepth: 2,
        urlPattern: 'edit?line={start}-{end}',
        linkText: 'edit',
        className: 'h{depth}'
    })
    .use(remarkRehype)
    .use(rehypeStringify)
    .process(await read('example.md'))

console.log(file.value)

then running node example.js yields:

<div class="h1"><h1>Level 1</h1><a href="edit?line=1-16">edit</a></div>
<p>paragraph</p>
<div class="h2"><h2>Level 2</h2><a href="edit?line=5-12">edit</a></div>
<p>paragraph</p>
<h3>Level 3</h3>
<p>paragraph</p>
<div class="h2"><h2>Level 2</h2><a href="edit?line=13-16">edit</a></div>
<p>paragraph</p>
<div class="h1"><h1>Level 1</h1><a href="edit?line=17-19">edit</a></div>
<p>paragraph</p>

Use with remark-CLI

npm install remark-cli
remark example.md --use remark-heading-lines
remark example.md --use remark-heading-lines --use remark-rehype -use rehype-stringify

API

The default export is remarkHeadingLines.

unified().use(remarkHeadingLines[, options])

Options

• position (string, optional) — position of the link relative to the headline. Possible values are append (put link inside h-tag at last index), prepend (put link inside h-tag at first index), after (put link after the h-tag) and before (put link before the h-tag). The after and before positions are wrapped in a div tag and require remark-rehype. Default is append.

• maxDepth (integer, optional) — maximum depth of headline hierarchy to render links. Default value is 6.

• urlPattern (string, optional) — pattern to generate the link. Placeholders are {start} and {end}. Default pattern is edit/{start}/{end}.

• linkText (string, optional) — text used for the link. Default text is Edit.

• className (string, optional) — style class to be added to the div wrapper when using position after or before. Placeholder is {depth}. Default is no style class.