https://github.com/thomd/rehype-navigation
rehype plugin which creates a navigation reflecting the headline hierarchy
https://github.com/thomd/rehype-navigation
rehype rehype-plugin
Last synced: 5 months ago
JSON representation
rehype plugin which creates a navigation reflecting the headline hierarchy
- Host: GitHub
- URL: https://github.com/thomd/rehype-navigation
- Owner: thomd
- License: mit
- Created: 2024-07-13T21:37:29.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-16T17:40:56.000Z (over 1 year ago)
- Last Synced: 2025-09-28T18:13:46.158Z (9 months ago)
- Topics: rehype, rehype-plugin
- Language: JavaScript
- Homepage: https://thomd.github.io/rehype-navigation/
- Size: 68.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# rehype-navigation
![Build][build-badge]
`rehype-navigation` is a [rehype][rehype] plugin to create a navigation with anchor links reflecting the headline hierarchy.
The plugin works best with headings having `id` attributes. You may use for example [rehype-slug][rehype-slug] to add them. If `id` attributes are missing, then the navigation is generated without anchor links.
## Demo
Generate the HTML for a demo page like this:
```
cd demo
node demo.js > index.html
npx http-server
open http://localhost:8080
```
or open this [demo page](https://thomd.github.io/rehype-navigation/).
## Usage
Say we have the following file `example.md`:
```markdown
# Level 1.1
## Level 2.1
text
## Level 2.2
text
# Level 1.2
text
```
and a module `example.js`:
```js
import { remark } from 'remark'
import remarkRehype from 'remark-rehype'
import rehypeSlug from 'rehype-slug'
import rehypeNavigation from 'rehype-navigation'
import rehypeStringify from 'rehype-stringify'
import { read } from 'to-vfile'
const file = await remark()
.use(remarkRehype)
.use(rehypeSlug)
.use(rehypeNavigation, { wrapperTag: 'nav', maxDepth: 3 })
.use(rehypeStringify)
.process(await read('example.md'))
console.log(file.value)
```
then running `node example.js` yields:
```html
Level 1.1
Level 2.1
text
Level 2.2
text
Level 1.2
text
```
## API
The default export is `rehypeNavigation`.
```js
unified().use(rehypeNavigation, options)
```
### Options
The following options are available:
- `extract` (`Boolean`, optional) — Generate only the navigation and remove everything else. Default is `false`.
- `maxDepth` (`Integer`, optional) — Maximum depth of the headings hierarchy which should be taken into account for the navigation. Default is `6`.
- `wrapperTag` (`String`, optional) — Tag to wrap the navigation. Default is no wrapper tag.
- `fullMonty` (`Boolean`, optional) — Generate navigation even if there is only **one** headline. Default is `true`.
[rehype]: https://github.com/rehypejs/rehype
[rehype-slug]: https://github.com/rehypejs/rehype-slug
[build-badge]: https://github.com/thomd/rehype-navigation/workflows/plugin-test/badge.svg