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.

[!WARNING] This plugin uses remark-comment. It may break other plugins that use comments.

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. This plugin must be inserted before the mdx() plugin if you are using it.

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

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

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