如何在Docusaurus中为页面元素添加id属性？

架构老林

2026-9-11

Docusaurus 内置的 Markdown/MDX 解析规则默认仅对标题元素开放 {#自定义ID} 语法支持，普通行内、块级元素直接套用原生 Markdown 的 {#ID} 写法不会被解析，因此无法正常生效。

零配置通用方案：直接书写原生HTML
Docusaurus 原生支持在 Markdown 内容中直接插入HTML标签，无需修改任何配置即可生效。比如需要给链接添加自定义ID，直接按HTML语法书写即可：
```
<a href="/some/text/etc" id="your-custom-id">Some Text</a>
```
给段落、容器等其他块级/行内元素添加ID的逻辑完全一致，直接给对应HTML标签添加id属性即可。
保留Markdown简写方案：扩展解析插件
如果需要继续使用[Some Text](/some/text/etc){#ID}这类原生Markdown简写语法，可以通过添加remark-attr插件扩展解析能力：
1. 安装插件依赖：
```
npm install remark-attr
# 使用yarn/pnpm的话替换为对应包管理工具的安装命令即可
```
2. 修改项目根目录下的docusaurus.config.js配置文件，在需要启用该语法的模块（文档、博客等）的remarkPlugins配置项中加入插件声明：
```
presets: [
  [
    '@docusaurus/preset-classic',
    {
      docs: {
        // 保留原有文档模块的其他配置
        remarkPlugins: [
          // 保留原有其他remark插件
          [require('remark-attr'), {}]
        ],
      },
      // 博客等其他模块需要开启该语法的话，同步在对应配置项中添加相同插件声明即可
    },
  ],
],
```
3. 重启本地开发服务或重新执行构建，之后{#自定义ID}写法就可以在所有支持的元素上正常生效。