如何在Docusaurus v3中自动为标题添加层级编号并支持单文档禁用？

全局启用标题编号 #

1. 打开项目中src/css/custom.css文件（无则新建），添加以下CSS代码：

/* 初始化一级标题计数器 */
:root {
  counter-reset: h2-counter;
}

/* 处理h2标题：递增计数器，重置下一级计数器 */
article h2 {
  counter-reset: h3-counter;
  counter-increment: h2-counter;
}
article h2::before {
  content: counter(h2-counter) ". ";
}

/* 处理h3标题 */
article h3 {
  counter-reset: h4-counter;
  counter-increment: h3-counter;
}
article h3::before {
  content: counter(h2-counter) "." counter(h3-counter) ". ";
}

/* 处理h4标题 */
article h4 {
  counter-reset: h5-counter;
  counter-increment: h4-counter;
}
article h4::before {
  content: counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) ". ";
}

/* 处理h5标题 */
article h5 {
  counter-reset: h6-counter;
  counter-increment: h5-counter;
}
article h5::before {
  content: counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) "." counter(h5-counter) ". ";
}

/* 处理h6标题 */
article h6 {
  counter-increment: h6-counter;
}
article h6::before {
  content: counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) "." counter(h5-counter) "." counter(h6-counter) ". ";
}

这段代码通过CSS计数器实现h2到h6的层级联动编号，每个层级标题出现时会自动重置下一级计数器，确保编号逻辑符合文档结构。

特定文档禁用编号 #

步骤1：在目标文档添加front matter标识 #

在需要取消编号的MD/MDX文档开头，添加自定义属性：

---
title: "无需编号的文档示例"
disableHeadingNumbering: true
---

步骤2：更新CSS规则 #

回到custom.css，追加以下代码：

/* 禁用标题编号的文档，清除所有计数器和前缀内容 */
article[data-disable-heading-numbering="true"] {
  counter-reset: none;
}

article[data-disable-heading-numbering="true"] h2,
article[data-disable-heading-numbering="true"] h3,
article[data-disable-heading-numbering="true"] h4,
article[data-disable-heading-numbering="true"] h5,
article[data-disable-heading-numbering="true"] h6 {
  counter-reset: none;
  counter-increment: none;
}

article[data-disable-heading-numbering="true"] h2::before,
article[data-disable-heading-numbering="true"] h3::before,
article[data-disable-heading-numbering="true"] h4::before,
article[data-disable-heading-numbering="true"] h5::before,
article[data-disable-heading-numbering="true"] h6::before {
  content: "";
}

步骤3：修改MDXContent组件传递标识 #

运行命令npm run swizzle @docusaurus/theme-classic MDXContent，选择wrap模式生成自定义组件，然后修改src/theme/MDXContent.js：

import React from 'react';
import MDXContent from '@theme/MDXContent';
import { useFrontMatter } from '@docusaurus/theme-common';

export default function MDXContentWrapper(props) {
  const frontMatter = useFrontMatter();
  return (
    <article
      data-disable-heading-numbering={frontMatter.disableHeadingNumbering ? "true" : "false"}
    >
      <MDXContent {...props} />
    </article>
  );
}

这段代码会把文档front matter中的disableHeadingNumbering属性绑定到article元素的data属性上，让CSS可以精准识别并禁用编号。

内容的提问来源于stack exchange，提问作者t4dhg