astro-custom-toc

astro-custom-toc

Astro Integration to generate a customizable table of contents. This is a convenient wrapper for rehype-custom-toc. If you are not using Astro, you can directly use rehype-custom-toc instead.

This plugin uses remark-comment when using the unified Markdown processor. It may break other plugins that use comments. When using the Sätteri processor (Astro v7 default), HTML comments are handled natively and remark-comment is not used.

Since astro-custom-toc v5 supports only Astro v7, please use v4 if you are using Astro v6.

Installation

npx astro add astro-custom-toc

Manual Install

Install the package

npm install astro-custom-toc

Add the plugin to your astro.config.mjs.

import { defineConfig } from "astro/config";
import customToc from "astro-custom-toc";

// https://astro.build/config
export default defineConfig({
    // ... other config
    integrations: [customToc()]
});

Markdown processor support

astro-custom-toc works with both Markdown processors supported by Astro v7:

• Sätteri (default): Astro's native Markdown pipeline. No extra setup is needed.
• Unified (remark/rehype): Set markdown.processor: unified() from @astrojs/markdown-remark to use this processor.

Usage

To include a table of contents in your markdown file, add showToc: true to the frontmatter of the markdown file. The table of contents will be inserted at the location of the <!-- toc --> comment or at the beginning of the file if no comment is found.

---
showToc: true
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

<!-- toc -->

## Section 1

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

### Subsection 1.1

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

Options

All options of rehype-custom-toc can be used in this plugin. Please refer to the rehype-custom-toc documentation for options.

Development

npm install

Build

npm run build

Format and Lint

npm run format
npm run lint

Pull Requests

This repository uses Changesets to manage versioning and releases. When creating a pull request, please run the Changesets CLI and commit the changeset file.

npx changeset