Sphinx配置myst-parser与Recommonmark时Markdown链接解析异常

异常输出的核心根因 #

你看到的半残HTML结构[some text](<a class="reference external" href="www.example.com">www.example.com</a>)，是同一个Markdown文件被两个解析器串行重复处理导致的：

1. rst域的内置链接逻辑先拦截了圆括号包裹的URL部分，将其替换为标准rst链接节点
2. 外层Markdown专属的[锚文本]语法是rst解析器无法识别的结构，会被原样保留到最终输出
3. 两个解析逻辑错位拼接，就出现了“一半被转成HTML标签、一半漏出原始Markdown语法”的异常效果。
   你之前换用recommonmark配置后问题没有消失，本质是没有从配置里移除myst-parser的加载逻辑，两个功能重叠的解析器同时抢占同一个.md文件的处理权限，解析流程完全错位。

具体修复步骤 #

1. 彻底清理冲突的扩展配置 #

recommonmark 与 myst-parser 是功能完全重叠的两套Markdown解析方案，同时加载必然触发解析冲突。优先选择仍在持续维护的myst-parser作为唯一解析器，从conf.py中删除所有recommonmark相关的冗余配置：

• 删除extensions列表中的recommonmark条目
• 整个移除source_parsers配置块（该配置是旧版recommonmark专属逻辑，myst不需要）
• 删除文件中所有recommonmark的import语句、以及setup函数中关联的AutoStructify、recommonmark_config相关逻辑

2. 修正myst-parser的文件匹配配置 #

按照myst-parser 0.13.6版本的适配要求，正确配置source_suffix，不要混用旧版的列表格式：

source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

注意：不要在同一份conf.py中同时存在myst-parser和recommonmark的扩展配置，两个扩展会抢占同一个.md文件的解析权限，是触发当前异常的最直接原因。

3. 修正链接格式的兼容配置 #

[锚文本](www.example.com)这种不带传输协议头的链接写法，默认情况下myst-parser会将其识别为页面内锚点，不会解析为外部链接，需要显式开启无协议链接的解析支持：
在conf.py中追加配置：

# 允许解析无协议头的外部链接
myst_url_schemes = ["http", "https", "ftp", "mailto"]

写Markdown链接时尽量补全完整的协议头（如[锚文本](https://www.example.com)），减少解析歧义。

4. 排除缓存与场景干扰 #

• 改动配置后先清空build目录下的所有旧缓存，Sphinx的增量构建会复用之前的解析结果，容易出现“改了配置不生效”的假象
• 检查所有rst文件中是否误用literalinclude引入了.md文件的内容，这种场景下的Markdown语法不会被解析，会原样展示在页面中

效果验证 #

配置修改完成后，写一个最小测试Markdown片段验证解析效果：

测试外部链接：[Sphinx官方文档](https://www.sphinx-doc.org)
测试无协议链接：[示例站点](www.example.com)

重新构建静态文件后，检查输出HTML的结构，正常效果应该是完整的可点击<a>标签，不会残留任何原始Markdown方括号文本。

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