fix(seo): prevent multiple h1 via remark heading shift

Bing Webmaster 报 4 个页面有多个 <h1>。仓库 324 个 MDX 里 181 个正文
都写了 # 一级标题（markdown 习惯），叠加 page.tsx 渲染的 <h1>{title}</h1>
形成双 h1，是 SEO/无障碍反模式。

不能要求贡献者改写习惯，所以在 build 阶段加 remark 插件自动处理：

  function remarkShiftHeadingIfH1(tree) {
    if (tree 含 h1) {
      所有 heading.depth += 1 (h1→h2 / h2→h3 / ... / h5→h6)
    }
  }

效果：
- 贡献者照常写 # 标题 / ## 章节 / ### 子节
- 渲染变 <h2> / <h3> / <h4>，保持层级关系
- page.tsx 的 <h1>{title}</h1> 是页面唯一 h1
- MDX 不含 h1 时不动 (作者已从 ## 起，天然合规)

本地验证：
- bq.html: 之前 2 h1 → 1 h1 ✅
- cs/index.html: 之前 3 h1 (含两个 # 中文混排) → 1 h1 ✅
- leetcode 抽样: 1 h1 ✅

历史背景：page.tsx 渲染 h1 是 2025-09-19 commit 7b270d5 加的，
社区贡献的 mdx 早就在写 # 一级标题，双 h1 隐患存在 8 个月直到 Bing
2026-05 扫描才报出。

Author: github-actions[bot]

source.config.ts

@@ -36,6 +36,38 @@ function remarkNormalizeCodeLang() {
   };
 }
 
+/**
+ * Remark 插件：避免双 h1
+ *
+ * 背景：Bing Webmaster 2026-05 报告 4 个页面有多个 <h1>，仓库里其实
+ * 181 / 324 个 MDX 正文都写了 `# 一级标题`。page.tsx 已经渲染了
+ * `<h1>{frontmatter.title}</h1>` 作为页面唯一 h1，MDX 正文里再写 `# x`
+ * 就形成双 h1，对 SEO/无障碍都是反模式。
+ *
+ * 不能要求贡献者注意这个约束（markdown 习惯就是 # 当顶级标题），所以
+ * 在 build 阶段自动 shift：如果 MDX 含 h1，整树 heading 降一级
+ * （h1→h2 / h2→h3 / ... / h5→h6）。这样：
+ *   - 贡献者照常写 `# 标题`、`## 章节`、`### 子节`
+ *   - 渲染出来变 `<h2>` / `<h3>` / `<h4>`，保持层级关系
+ *   - page.tsx 的 `<h1>` 是页面唯一 h1
+ *
+ * 如果 MDX 不含 h1（作者已经从 ## 开始）就不动 —— 这种文档天然合规。
+ *
+ * 副作用：MDX 用到 h5 时会被降到 h6；h6 已是 markdown 最大深度无法再降，
+ * 这里保留为 h6（罕见，CS/AI 技术文档基本不到 5 层）。
+ */
+function remarkShiftHeadingIfH1() {
+  return (tree: Root) => {
+    const hasH1 = tree.children.some(
+      (n) => n.type === "heading" && n.depth === 1,
+    );
+    if (!hasH1) return;
+    visit(tree, "heading", (node) => {
+      if (node.depth < 6) node.depth += 1;
+    });
+  };
+}
+
 /**
  * CRITICAL: Fumadocs 图片处理配置
  *
@@ -86,13 +118,18 @@ const imageOptions = {
  * 包含：
  * - remarkMath：启用 Markdown 数学语法支持 ($...$, $$...$$)
  * - remarkNormalizeCodeLang：将代码块语言标识符转为小写（解决 Shiki 大小写问题）
+ * - remarkShiftHeadingIfH1：mdx 含 h1 时整树 heading 降一级，避免与 page.tsx 的 h1 冲突
  * - rehypeKatex：使用 KaTeX 将数学公式渲染为 HTML（strict:false 更宽松）
  * - remarkImageOptions：图片处理配置（禁用远程尺寸探测，见上方注释）
  */
 export default defineConfig({
   mdxOptions: {
-    // 支持 LaTeX 公式 + 规范化代码块语言标识符
-    remarkPlugins: [remarkMath, remarkNormalizeCodeLang],
+    // 支持 LaTeX 公式 + 规范化代码块 + h1 降级避免双 h1
+    remarkPlugins: [
+      remarkMath,
+      remarkNormalizeCodeLang,
+      remarkShiftHeadingIfH1,
+    ],
 
     // 宽松的 KaTeX 渲染，不因轻微语法错误中断
     rehypePlugins: (v) => [[rehypeKatex, { strict: false }], ...v],