remark plugin that automatically inserts one or more specified headings into the AST.
A remark plugin that ensures specific headings are present in the Markdown document by inserting them into the AST at defined positions if they are missing.
Several popular remark plugins (such as remark-toc) rely on specific headings being present in the input document.
By design, these plugins typically do not create the headings themselves, but instead assume they exist and use them as anchors or insertion points for additional content.
This is where remark-insert-headings comes in - it ensures those headings are present before other plugins run.
It's especially useful when:
- You're parsing auto-generated content.
- You're working from templates and don't want to include heading markers manually in input files.
As with other plugins in the remark ecosystem, this package is ESM only.
npm install remark-insert-headingsSay we have the following file example.md document:
# Main heading
Some para
## Content Heading A
Some para
## Content Heading B...and a script example.js:
import fs from 'node:fs/promises';
import { remark } from 'remark';
import remarkInsertHeadings from 'remark-insert-headings';
import remarkToc from 'remark-toc';
import remarkLicense from 'remark-license';
const document = await fs.readFile('example.md', 'utf8');
const file = await remark()
.use(remarkInsertHeadings, [
{
text: 'Contents',
position: 'start',
minHeadingCount: 2,
},
{
text: 'License',
position: 'end',
},
])
.use(remarkToc)
.use(remarkLicense)
.process(document);
console.log(String(file));...then running node example.js yields:
# Main heading
## Contents
- [Content Heading A](#content-heading-a)
- [Content Heading B](#content-heading-b)
- [License](#license)
## Content Heading A
Some para
## Content Heading B
Some para
## License
[MIT](LICENSE) © John DoeThe default export is remarkInsertHeadings.
This plugin:
- Adds a heading to the document if it doesn't already exist.
- Should be run before dependent plugins that expect those headings to be present.
Note: All inserted headings use ## (i.e., heading depth 2) by default.
options (Options)
Transform (Transformer).
You can define multiple headings to insert at various positions. The order of the headings will be preserved as defined in the configuration.
You can also pass a single object if you're only inserting one heading.
Each field supports the following:
text(string) — The text content of the heading to insert.position("start"|"end") — Where to insert the heading:"start": after the first paragraph but before the next heading."end": at the end of the document.
minHeadingCount(number, default0) — Only insert the heading if the document contains more than this number of headings of depth 2.
The plugin might be useful to configure the following plugins: