实验性 Markdown 标题 ID 兼容性

类型：boolean
默认：false

¥Type: boolean
Default: false

Added in: astro@5.5.0 新

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

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

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

¥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

此实验性标志允许你保留以特殊字符结尾的 Markdown 标题 ID 末尾的尾随连字符，从而创建与其他常见平台生成的 ID 兼容的 ID。它不需要特定用法，只会影响 Astro 如何为使用 Markdown 语法编写的标题生成 id。

¥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 与许多平台一样，使用流行的 github-slugger 包将 Markdown 标题的文本内容转换为 slug 以用于 ID。此实验性标志允许你省略 Astro 的额外默认处理步骤，该步骤会从以特殊字符结尾的标题的 ID 末尾删除尾随连字符。

¥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.

例如，以下 Markdown 标题：

¥For example, the following Markdown heading:

## `<Picture />`

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

¥will generate the following HTML in Astro by default:

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

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

¥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>

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

¥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.

与 rehypeHeadingIds 插件一起使用

标题部分 与 rehypeHeadingIds 插件一起使用

¥Usage with rehypeHeadingIds plugin

如果你直接使用 使用 rehypeHeadingIds 插件，请在 Astro 配置中传递插件时选择加入兼容模式：

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