实验性 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 兼容的 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 等平台的 HTML 相同

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

在未来的主要版本中，Astro 将默认切换到使用兼容的 ID 样式，但你可以使用 experimental.headingIdCompat 标志提前选择加入未来的行为。

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