# remark-custom-header-id

> Remark plugin for adding a custom ID attribute to Markdown headers

Latest version **1.0.0** (published 2024-05-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install remark-custom-header-id
pnpm add remark-custom-header-id
yarn add remark-custom-header-id
bun add remark-custom-header-id
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2024-05-28 |
| First published | 2024-03-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 4.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 46 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | remark, remark-plugin, markdown, header, heading, unified, plugin, html, id, attribute, astro |

## Links

- npm: https://www.npmjs.com/package/remark-custom-header-id
- Repository: https://github.com/sindresorhus/remark-custom-header-id
- Homepage: https://github.com/sindresorhus/remark-custom-header-id#readme
- Issues: https://github.com/sindresorhus/remark-custom-header-id/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/remark-custom-header-id

## Dependencies (2)

- [@types/unist](https://npm.io/package/@types/unist.md) ^3.0.2
- [unist-util-visit](https://npm.io/package/unist-util-visit.md) ^5.0.0

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2024-05-28
- 0.1.0 — 2024-03-11

## 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));
//=> '<h1 id="custom-id">Foo</h1>'
```

### 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.

---
_Source: https://npm.io/package/remark-custom-header-id · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._