如何在 Sphinx 网站中自定义 Markdown 标题样式（居中+加粗）-html教程-PHP中文网

如何在 Sphinx 网站中自定义 Markdown 标题样式（居中+加粗）

本文详解如何在 Sphinx 文档中为 Markdown 标题（如 # MyHeader）实现居中对齐与加粗效果，涵盖纯 CSS 方案、MyST 扩展属性语法，并解决原始 HTML 标题导致 TOC 失效的问题。

本文详解如何在 sphinx 文档中为 markdown 标题（如 # myheader）实现居中对齐与加粗效果，涵盖纯 css 方案、myst 扩展属性语法，并解决原始 html 标题导致 toc 失效的问题。

Sphinx 默认将 Markdown 中的 # MyHeader 渲染为语义化 <h1></h1> 标签，但其样式受主题 CSS 控制。直接在 _static/css/custom.css 中写 .center h1 { text-align: center; } 无效，是因为该选择器要求 <h1></h1> 是类名为 center 的元素的子元素（即 <div class="center"><h1>...</h1></div>），而实际 HTML 并无外层容器。

✅ 推荐方案一：全局统一设置（最简可靠）
若希望所有一级标题均居中且加粗，只需在 _static/css/custom.css 中添加：

h1 {
  text-align: center;
  font-weight: bold;
}

确保已在 conf.py 中启用自定义 CSS：

html_static_path = ['_static']
html_css_files = ['css/custom.css']

✅ 推荐方案二：按需定制（语义清晰 + 灵活复用）
Sphinx（配合 MyST-Parser）支持通过 attrs_block 扩展为标题添加 HTML 属性。首先确认 conf.py 中已启用该扩展：

myst_enable_extensions = [
    "attrs_block",
    # 其他扩展...
]

然后在 Markdown 文件中使用属性块语法：

{.center .bold}
# MyHeader

对应 CSS（同样放入 custom.css）：

Markdown to HTML

{"answer":"将 Markdown 转换为内嵌 CSS、样式精美的独立 HTML。完美适用于新闻简报、文档、报告及邮件模板。"}

下载

h1.center {
  text-align: center;
}
h1.bold {
  font-weight: bold;
}
/* 或合并写法 */
h1.center.bold {
  text-align: center;
  font-weight: bold;
}

⚠️ 为什么不建议直接写 HTML？
虽然 <h1 style="text-align:center;"><b>MyHeader</b></h1> 在页面上显示正常，但 Sphinx 的文档解析器无法从中提取标题文本用于生成页面元数据（如 title 变量）和导航结构（TOC tree），导致该页面在侧边栏目录中显示为 <no title></no>，甚至可能从 toctree 中消失。因此，必须通过标准 Markdown 标题语法（#）触发 Sphinx 的标题识别机制。

? 额外提示：

若使用 sphinx-book-theme 或 furo 等现代主题，请检查其是否重置了 h1 样式（可添加 !important 临时调试，但生产环境建议覆盖主题变量而非滥用 !important）；
加粗效果优先使用 font-weight: bold（语义正确），而非 <b></b> 标签——后者仅是表现层标签，且破坏 Markdown 的可维护性；
修改 CSS 后务必清除浏览器缓存或禁用缓存调试，避免样式未生效的误判。

综上，结合 MyST 的 attrs_block 扩展与精准 CSS 选择器，既能保持 Sphinx 的标题语义与 TOC 功能完整，又能实现灵活、可维护的样式定制。