Experimental Markdown heading ID compatibility

Type: boolean
Default: false

追加： astro@5.5.0 New

The experimental.headingIdCompat flag makes the IDs generated by Astro for Markdown headings compatible with common platforms like GitHub and npm.

To enable heading ID compatibility, set the flag to true in your Astro configuration:

astro.config.mjs

import { defineConfig } from "astro/config"

export default defineConfig({
  experimental: {
    headingIdCompat: true,
  }
})

Usage

Section titled Usage

This experimental flag allows you to retain the trailing hyphens on the end of IDs for Markdown headings ending in special characters, creating IDs compatible with those generated by other common platforms. It requires no specific usage and only affects how Astro generates the id for your headings written using Markdown syntax.

Astro, like many platforms, uses the popular github-slugger package to convert the text content of a Markdown heading to a slug to use in IDs. This experimental flag allows you to omit Astro’s additional default processing step that strips a trailing hyphen from the end of IDs for headings ending in special characters.

For example, the following Markdown heading:

## `<Picture />`

will generate the following HTML in Astro by default:

<h2 id="picture"><code>&lt;Picture /&gt;</h2>

Using experimental.headingIdCompat, the same Markdown will generate the following HTML, which is identical to that of platforms such as GitHub:

<h2 id="picture-"><code>&lt;Picture /&gt;</h2>

In a future major version, Astro will switch to use the compatible ID style by default, but you can opt in to the future behavior early using the experimental.headingIdCompat flag.

Usage with rehypeHeadingIds plugin

Section titled Usage with rehypeHeadingIds plugin

If you are using the rehypeHeadingIds plugin directly, opt in to the compatibility mode when passing the plugin in your Astro configuration:

astro.config.mjs

import { defineConfig } from 'astro/config';
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [rehypeHeadingIds, { headingIdCompat: true }],
      otherPluginThatReliesOnHeadingIDs,
    ],
  },
});