Azure DevOps仓库中R Markdown生成的README图片无法显示问题咨询

问题背景 #

我们团队的Azure DevOps仓库内有一个R项目，使用R Markdown以github_document为输出格式生成README文件。插入图片的代码如下：

![Fig. 1 - Parameters to select](./images/Knit_with_params.png)

仓库中已上传images文件夹及其中的knit_with_params.png图片，本地R Markdown文档和RStudio生成的HTML预览均能正常显示图片，但生成的README.md中图片引用被转换为HTML figure标签：

<figure>
<img src="/images/Knit_with_params.png"
alt="Fig. 1 - Parameters to select" />
<figcaption aria-hidden="true">Fig. 1 - Parameters to
select</figcaption>
</figure>

将该README推送至仓库后，图片仅显示占位符；同事手动修改为标准Markdown图片引用后恢复正常：

![Fig. 1 - Parameters to select](/images/Knit_with_params.png)

但在R Markdown中移除路径前的.，本地会提示(No image at path /images/Knit_with_params.png)且HTML预览无法显示；只要生成的是figure标签而非标准图片引用，仓库中README的图片就无法正常显示。

1. 为什么figure标签在Azure DevOps仓库中无法生效？ #

Azure DevOps的Markdown渲染引擎基于GitHub Flavored Markdown（GFM）但做了定制化限制，对原生HTML标签的支持有限。它优先解析标准Markdown图片语法![alt文本](图片路径)，而不会完整渲染<figure>这类结构化HTML标签，导致图片路径无法被正确识别，最终仅显示占位符。

2. 如何让R Markdown生成标准图片引用而非figure标签？ #

可以通过以下方式配置R Markdown，避免生成figure标签，同时解决本地与仓库路径不一致的问题：

方式一：修改YAML输出配置 #

在R Markdown的YAML头部添加fig_caption: false，禁用自动生成figure标签的功能，生成的Markdown会直接使用标准图片语法：

---
output:
  github_document:
    fig_caption: false
---

此方式下，图片的标题会保留为alt文本的一部分，与你原本的写法一致，且本地预览和仓库显示均正常。

方式二：配置knitr全局选项 #

在R Markdown文档开头添加代码块，强制knitr输出标准Markdown图片语法：

knitr::opts_chunk$set(fig.show = "asis")

若需要更精细化控制，也可以针对单个图片手动输出标准语法：

cat('![Fig. 1 - Parameters to select](./images/Knit_with_params.png)')

适配本地与仓库路径差异 #

为解决本地路径带.、仓库路径不带.的矛盾，可设置knitr的base.url选项，让生成的Markdown自动使用仓库兼容的路径：

knitr::opts_knit$set(base.url = "/")

这样本地渲染时会自动适配路径，生成的README.md中图片路径会变为/images/...，无需手动修改即可同时满足本地预览和仓库显示需求。

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