Pandoc转换.md至.docx时部分图片显示‘无法显示’问题求助

问题场景 #

将Git Wiki中的Markdown文件转为Docx时，部分图片无法显示，问题由图片URL结构决定，与图片本身无关：

• 无法显示的图片URL示例：

  ![irr](https://git.{project}.com/pb/{project}/-/wikis/uploads/addf556fa0eaea08b97955c5da7b6229/02_01_Funds___IRR.png)
  

• 同一图片上传至第三方图床（如Imgur）可正常显示：

  ![irr_imgur](https://i.imgur.com/{image_id}.png) 
  

• 同一Git Wiki中路径结构不同的图片URL可正常显示：

  ![vc-benchmarking-fund](https://git.{project}.com/pb/{project}/uploads/06befbe869ba02844f344f86adc1f1f4/vc-benchmarking-fund.png)
  

Pandoc转换过程无报错，开启verbose日志显示已"获取"图片，但对应图片未被嵌入Docx文件。使用的转换命令：

pandoc C:\GitWiki\Mediator\Business-Domain\Funds\Advanced-Search-Funds-IRR-Search-functionality.md -s -o C:\GitWiki\Migrated\Business-Domain\Funds\Advanced-Search-Funds-IRR-Search-functionality.docx 

原因定位 #

问题根源在URL中的-/wikis/路径段：
Git Wiki的图片存储分为两类：

1. 直接上传至项目仓库的图片：路径为/pb/{project}/uploads/...，这类URL是公开可直接访问的静态资源，Pandoc能正常抓取并嵌入Docx；
2. 上传至Wiki页面的图片：路径包含-/wikis/uploads/...，这类URL依赖Git平台的内部重定向，且可能带有临时权限校验逻辑。Pandoc日志显示的"获取"仅代表发起了请求，但实际拿到的可能是权限验证页面而非图片文件，因此无法嵌入Docx。

解决办法 #

方法1：修改URL路径结构 #

将无法显示的图片URL中的-/wikis/uploads/替换为/uploads/，示例：
原URL：

https://git.{project}.com/pb/{project}/-/wikis/uploads/addf556fa0eaea08b97955c5da7b6229/02_01_Funds___IRR.png

修改后：

https://git.{project}.com/pb/{project}/uploads/addf556fa0eaea08b97955c5da7b6229/02_01_Funds___IRR.png

该方法的有效性已由同一Git Wiki中正常显示的图片路径验证。

方法2：本地引用图片 #

1. 手动下载无法显示的图片，保存到Markdown文件所在目录；
2. 将Markdown中的图片引用改为本地路径，示例：

   ![irr](./02_01_Funds___IRR.png)
   

3. 重新执行Pandoc转换命令，确保本地图片被正确嵌入。

方法3：添加认证参数（若Git平台需权限） #

如果Git Wiki的图片需要身份验证才能访问，在Pandoc命令中添加认证请求头：

pandoc --request-header="Authorization: Bearer {your_personal_access_token}" C:\GitWiki\Mediator\Business-Domain\Funds\Advanced-Search-Funds-IRR-Search-functionality.md -s -o C:\GitWiki\Migrated\Business-Domain\Funds\Advanced-Search-Funds-IRR-Search-functionality.docx

注意：需在Git平台生成具有Wiki图片读取权限的个人访问令牌（PAT）。

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