如何在Sphinx中引用已渲染的Markdown文件及解决链接问题

核心思路 #

要同时实现Markdown内容嵌入和指向渲染后页面的链接，需要让Sphinx正确识别目标文档的构建路径，结合myst-parser的特性处理跨文档引用逻辑。

可行方案1：调整文档配置+使用内部引用 #

• 确保docs/readme.md被纳入Sphinx构建范围：在conf.py的source_suffix中添加.md，并在index.rst或对应toctree里包含readme（无需加后缀）。
• 在readme_include.md中使用Sphinx内部引用语法：

  详情请参考[项目说明](readme)
  

• 在Dummy类的docstring中引入readme_include.md时，使用相对于Sphinx源目录（一般为docs/）的路径：

  class Dummy:
      """
      这是一个示例类。
  
      {include docs/readme_include.md}
      """
  

• 在conf.py中配置myst_include_dirs，确保Sphinx能定位到要引入的文件：

  myst_include_dirs = ['.']  # 指向当前源目录（docs/）
  

可行方案2：直接在docstring中整合嵌入与链接 #

如果不想额外维护中间文件readme_include.md，可以直接在docstring里同时实现内容嵌入和页面跳转：

class Dummy:
    """
    这是一个示例类。

    {include docs/readme.md}

    如需查看完整说明，可跳转至[项目说明](readme)
    """

该方式既嵌入了readme.md的内容，又能生成指向渲染后readme.html的有效链接。

常见问题排查 #

• 出现「Unknown source document」警告：检查readme.md是否被Sphinx纳入构建列表，确认toctree已包含该文档，且conf.py的exclude_patterns未排除它。
• 嵌入内容不渲染：确认myst-parser已安装，且conf.py的extensions中添加了'myst_parser'，同时myst_include_dirs配置正确。

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