实验性 Markdown 标题 ID 兼容性

类型： boolean
默认值： false

添加于： astro@5.5.0 新

experimental.headingIdCompat 标志使 Astro 为 Markdown 标题生成的 ID 与 GitHub 和 npm 等常见平台兼容。

要启用标题 ID 兼容性，请在 Astro 配置中将该标志设置为 true：

astro.config.mjs

import { defineConfig } from "astro/config"

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

用法

段落标题 用法

该实验性标志允许你在 Markdown 标题以特殊字符结尾时，保留 ID 尾部的连字符（-），从而生成与其他常见平台兼容的 ID。它无需特定用法，仅影响 Astro 对使用 Markdown 语法编写的标题生成 ID 的方式。

与其他平台一样，Astro 使用流行的 github-slugger 包将 Markdown 标题的文本内容转换为 slug 以用于 ID。此实验性标志允许你省略 Astro 的额外默认处理步骤——即当标题以特殊字符结尾时，自动移除 ID 末尾的连字符。

例如以下 Markdown 标题：

## `<Picture />`

在 Astro 中默认情况下将生成以下 HTML：

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

使用 experimental.headingIdCompat, 相同的 Markdown 将生成以下 HTML，与 GitHub 等平台相同：

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

在未来的主要版本中，Astro 将默认使用兼容的 ID 样式，但你可以提前使用 experimental.headingIdCompat 标志提前启用这一未来行为。

与 rehypeHeadingIds 插件一起使用

段落标题 与 rehypeHeadingIds 插件一起使用

如果你直接使用 rehypeHeadingIds 插件，需在 Astro 配置中传入插件时启用兼容模式：

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,
    ],
  },
});