https://github.com/sindresorhus/remark-custom-header-id

Remark plugin for adding a custom ID attribute to Markdown headers
https://github.com/sindresorhus/remark-custom-header-id

markdown nodejs npm remark remark-plugin

Last synced: about 13 hours ago
JSON representation

Remark plugin for adding a custom ID attribute to Markdown headers

• Host: GitHub
• URL: https://github.com/sindresorhus/remark-custom-header-id
• Owner: sindresorhus
• License: mit
• Created: 2024-03-11T06:32:42.000Z (11 months ago)
• Default Branch: main
• Last Pushed: 2024-05-28T17:45:36.000Z (8 months ago)
• Last Synced: 2025-01-31T15:24:37.855Z (5 days ago)
• Topics: markdown, nodejs, npm, remark, remark-plugin
• Language: JavaScript
• Homepage:
• Size: 6.84 KB
• Stars: 36
• Watchers: 2
• Forks: 4
• Open Issues: 0
• Metadata Files:
  • Readme: readme.md
  • License: license

Awesome Lists containing this project

README

        
# remark-custom-header-id

> [Remark](https://github.com/remarkjs/remark) plugin for adding a custom ID attribute to Markdown headers

This allows for stable and more meaningful anchor links in your generated HTML.

## Install

```sh

npm install remark-custom-header-id

```

## Usage

### Remark

```js

import {remark} from 'remark';

import remarkRehype from 'remark-rehype';

import rehypeStringify from 'rehype-stringify';

import remarkCustomHeaderId from 'remark-custom-header-id';

const file = await remark()

	.use(remarkCustomHeaderId)

	.use(remarkRehype) // Markdown to HTML

	.use(rehypeStringify) // Stringify the HTML

	.process('# Foo {#custom-id}');

console.log(String(file));

//=> '
Foo
'

```


### Astro

```js

// astro.config.js

import remarkCustomHeaderId from 'remark-custom-header-id';

export default defineConfig({

	// …

	markdown: {

		remarkPlugins: [

			remarkCustomHeaderId,

		],

	},

	// …

});

```

### Alternative syntax for MDX files

The `{#custom-id}` notation does not work in [MDX](https://mdxjs.com) files because MDX treats `{}` as JSX syntax, causing a parsing error. 

You can use one of these alternatives:

- Escape curly braces: `\{#custom-id\}`

- Use this syntax: `||custom-id||`

Examples:

- `## Some header \{#custom-id\}`

- `## Some header ||custom-id||`

## API

### remarkCustomHeaderId()

Returns a transformer function to be used with Remark.