如何阻止MyST修改Markdown文件中的图片路径？

• 方法一：启用MyST相对链接保留配置
  在Sphinx的conf.py中添加以下配置，让MyST保留原始相对路径结构：

  myst_relative_links = True
  

  这个配置会告诉MyST不要调整相对链接的层级，保持Markdown文件中写的../_static/figures/image.png路径不变。

• 方法二：使用Sphinx原生图片指令替代Markdown语法
  如果配置调整无效，可以直接用Sphinx的reStructuredText图片指令，MyST不会修改这类指令里的路径：

  .. image:: ../_static/figures/image.png
     :alt: 图片描述
  

  这种方式完全绕过MyST对Markdown图片路径的处理，确保路径原样保留。

• 方法三：自定义Sphinx变换恢复路径
  要是上面两种方法都不适用，可以在conf.py中添加自定义变换，在MyST解析后自动补回被移除的../前缀：

  from sphinx.transforms import SphinxTransform
  from docutils.nodes import image
  
  class RestoreImagePrefix(SphinxTransform):
      default_priority = 999  # 确保在其他变换之后执行
  
      def apply(self):
          # 遍历所有图片节点，补回路径前缀
          for img_node in self.document.traverse(image):
              uri = img_node['uri']
              if uri.startswith('_static/figures/') and not uri.startswith('../'):
                  img_node['uri'] = f'../{uri}'
  
  def setup(app):
      app.add_transform(RestoreImagePrefix)
  

  这段代码会在文档处理的最后阶段，把被修改的图片路径恢复成原始的相对路径。

内容的提问来源于stack exchange，提问作者Joshua von Damm