如何在reStructuredText(Sphinx)中嵌入HTML/XML以实现浏览器渲染？

我来帮你搞定这个问题！你尝试的raw指令其实就是正确的工具，但大概率是缩进格式不对导致的失效——reStructuredText对块级内容的缩进要求非常严格，这也是很多人踩坑的点。

正确的raw指令用法 #

要让HTML/XML被浏览器正常渲染，必须遵守以下规则：

1. 写.. raw:: html指令后，空一行
2. 后续的HTML/XML代码必须比raw指令行多缩进至少4个空格（推荐用空格，避免制表符的兼容性问题）

示例1：嵌入HTML链接 #

.. raw:: html

    <a href="testurl">点击跳转测试链接</a>

示例2：嵌入MathML代码 #

.. raw:: html

    <math><apply><plus/><ci>a</ci><apply><minus/><ci>b</ci><ci>c</ci></apply></apply></math>

为什么你之前的尝试失败？ #

• literal/code：这两个指令是用来展示代码文本的，会自动转义HTML标签，所以浏览器只会显示代码而非渲染
• container：只是用来分组内容的容器，不会处理原生HTML/XML
• raw指令使用错误：如果没有正确缩进，Sphinx会把后面的HTML当成普通段落文本，要么转义显示，要么直接忽略

额外注意事项 #

• 检查你的Sphinx配置文件conf.py，确保raw_enabled = True（默认是开启的，但如果被手动禁用了要改回来）
• 对于XML类内容（比如MathML），要确保目标浏览器支持该类型的渲染，部分旧浏览器可能需要额外的JS库（比如MathJax）来兼容
• 多行HTML/XML内容要保持统一的缩进级别，不要混合不同的缩进量

这样处理后，你的HTML/XML代码就会完整保留在生成的HTML文件中，并被浏览器正常渲染啦！

内容的提问来源于stack exchange，提问作者Ralph B.