# remark-mdx-toc

> A remark plugin to generate toc and convert it into MDX export

Latest version **0.3.1** (published 2022-08-01) · GPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install remark-mdx-toc
pnpm add remark-mdx-toc
yarn add remark-mdx-toc
bun add remark-mdx-toc
```

## Health

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

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

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.1 |
| Published | 2022-08-01 |
| First published | 2021-11-27 |
| Weekly downloads | 0 |
| License | GPL-3.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 41.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 17 |
| Author | DCsunset |
| Maintainers | dcsunset |
| Keywords | remark, mdx, toc |

## Links

- npm: https://www.npmjs.com/package/remark-mdx-toc
- Repository: https://github.com/DCsunset/remark-mdx-toc
- Homepage: https://github.com/DCsunset/remark-mdx-toc#readme
- Issues: https://github.com/DCsunset/remark-mdx-toc/issues
- npm.io page: https://npm.io/package/remark-mdx-toc

## Dependencies (5)

- [unified](https://npm.io/package/unified.md) ^10.1.2
- [unist-util-visit](https://npm.io/package/unist-util-visit.md) ^4.1.0
- [mdast-util-to-string](https://npm.io/package/mdast-util-to-string.md) ^3.1.0
- [estree-util-value-to-estree](https://npm.io/package/estree-util-value-to-estree.md) ^1.3.0
- [estree-util-is-identifier-name](https://npm.io/package/estree-util-is-identifier-name.md) ^2.0.1

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 0.3.1 (latest) — 2022-08-01
- 0.3.0 — 2022-07-15
- 0.2.0 — 2022-07-09
- 0.1.0 — 2021-11-27

## README

# remark-mdx-toc

[![Version](https://img.shields.io/npm/v/remark-mdx-toc.svg)](https://npmjs.org/package/remark-mdx-toc)

A remark plugin to generate toc and convert it into MDX export

## Installation

```
npm install remark-mdx-toc
```

Note: This package uses [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
Use Node 12+ and ESM import syntax to use this package.

## Usage

```js
import { remarkMdxToc } from "remark-mdx-toc";
// This uses @mdx-js/mdx v2
import { compileSync } from "@mdx-js/mdx";
import fs from "fs";

const content = compileSync(fs.readFileSync("example.mdx"), {
  jsx: true,
  remarkPlugins: [remarkMdxToc],
  // Or specify the exported identifier
  // remarkPlugins: [
  //   [remarkMdxToc, { name: "toc" }]
  // ]
});

console.log(content.value);
```

Suppose the `example.mdx` has the following content:

```md
# Hello, world {#hello-world}

## Title 1

Content 1

### Subtitle 1

Sub Content 1

<h2 id="title-2">Title 2</h2>

Content 2
```

Then the output of the above code is similar to the following:

```jsx
export const toc = [{
  "depth": 1,
  "value": "Hello, world",
  "attributes": {
    "id": "hello-world"
  },
  "children": [{
    "depth": 2,
    "value": "Title 1",
    "attributes": {},
    "children": [{
      "depth": 3,
      "value": "Subtitle 1",
      "attributes": {},
      "children": []
    }]
  }, {
    "depth": 2,
    "value": "Title 2",
    "attributes": { "id": "title-2" }
    "children": []
  }]
}];

function MDXContent(props = {}) {
  // ...
}
export default MDXContent;
```

- HTML heading tags (`h1`-`h6`) are supported.
- Custom tags can also be added through options.
- `{#id}` syntax needs [remark-heading-id](https://github.com/imcuttle/remark-heading-id) plugin.

## Options

* `name`: The exported variable name of the toc. By default, it's `toc`.
* `customTags`: Add custom tags to toc.

`customTags` is an array of `CustomTag` defined below:

```ts
type CustomTag = {
  /// regex to match the tag name
  name: RegExp,
  /// get depth from name
  depth: (name: string) => number
}
```


## License

GPL-3.0

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