能否在m2r2中用MD远程链接替代本地路径实现rst嵌入渲染？

核心结论 #

m2r2自带的mdinclude指令仅支持本地文件路径，无法直接加载远程MD链接。要实现无需本地下载的远程MD渲染，需要借助额外脚本、自定义扩展或预构建处理。

可用方法与工具 #

1. Sphinx配置中添加远程内容注入 #

在Sphinx的conf.py里通过自定义脚本拉取远程MD内容，再通过rst_prolog自动插入到文档中：

import requests

def get_remote_md(url):
    res = requests.get(url)
    res.raise_for_status()
    return res.text

# 拉取目标远程MD内容并转为可渲染的markdown块
remote_content = get_remote_md("https://github.com/apache/kafka/blob/trunk/PULL_REQUEST_TEMPLATE.md")
rst_prolog = f"""
.. raw:: markdown

    {remote_content}
"""

之后构建文档时，这段远程MD内容会自动插入到所有rst文档的开头，也可以针对单个文档单独处理。

2. 自定义Sphinx扩展实现远程引用指令 #

编写一个简单的Sphinx扩展，新增支持远程链接的remote-mdinclude指令：

from docutils.parsers.rst import Directive
import requests
from m2r2 import convert

class RemoteMDInclude(Directive):
    required_arguments = 1

    def run(self):
        url = self.arguments[0]
        res = requests.get(url)
        res.raise_for_status()
        # 将远程MD转为reStructuredText节点
        rst_content = convert(res.text)
        return self.state.parse(rst_content, self.state_machine)

def setup(app):
    app.add_directive("remote-mdinclude", RemoteMDInclude)
    return {"version": "0.1", "parallel_read_safe": True}

将该扩展保存为remote_md_ext.py，在conf.py中添加extensions = ["remote_md_ext"]，之后就能在rst文件中直接使用：

.. remote-mdinclude:: https://github.com/apache/kafka/blob/trunk/PULL_REQUEST_TEMPLATE.md

3. 预构建脚本批量替换远程链接 #

在调用m2r2转换前，用脚本自动替换rst文件中的远程MD链接为拉取后的内容（以bash脚本为例）：

#!/bin/bash
# 替换所有远程mdinclude指令为对应的raw markdown块
sed -i -E 's/\.\. mdinclude:: (https.*)/echo ".. raw:: markdown\n\n$(curl -s \1)"/e' your_doc.rst

这种方法会直接修改本地rst文件，适合一次性构建的场景。

注意事项 #

• 网络依赖：所有方法都要求构建环境能正常访问目标远程链接，需处理超时、权限等异常情况。
• 缓存优化：建议添加本地缓存逻辑，避免每次构建重复拉取相同内容，提升构建效率。
• 格式兼容：远程MD的语法可能与m2r2的解析规则存在差异，需测试验证最终渲染效果。

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