https://github.com/thomd/remark-heading-lines
remark plugin to add a link to a headline containing start- and end-lines of a heading section
https://github.com/thomd/remark-heading-lines
ast markdown remark remark-plugin
Last synced: 4 months ago
JSON representation
remark plugin to add a link to a headline containing start- and end-lines of a heading section
- Host: GitHub
- URL: https://github.com/thomd/remark-heading-lines
- Owner: thomd
- License: mit
- Created: 2024-05-15T20:52:36.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-16T17:44:05.000Z (over 1 year ago)
- Last Synced: 2025-08-29T06:17:58.841Z (10 months ago)
- Topics: ast, markdown, remark, remark-plugin
- Language: JavaScript
- Homepage:
- Size: 120 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# remark-heading-lines
![Build][build-badge]
`remark-heading-lines` is a [remark][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`:
```markdown
# Level 1
paragraph
## Level 2
paragraph
### Level 3
paragraph
## Level 2
paragraph
# Level 1
paragraph
```
and a module `example.js`:
```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:
```html
paragraph
paragraph
Level 3
paragraph
paragraph
paragraph
```
## Use with remark-CLI
```bash
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`.
```js
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.
[remark]: https://github.com/remarkjs/remark
[build-badge]: https://github.com/thomd/remark-heading-lines/workflows/plugin-test/badge.svg