MkDocs正常显示的图片链接在GitHub仓库无法加载的解决方法

问题根源 #

你用的/../../images/是多级向上跳转的相对路径，本地MkDocs预览时的服务器目录结构，和GitHub Pages部署后的站点根目录结构不一致，导致路径解析失败，图片加载不出来。

修复方案 #

第一步：规范图片存放位置（推荐） #

先把图片放到MkDocs标准的docs/images目录下，项目结构参考：

你的项目文件夹/
├── docs/
│   ├── images/
│   │   ├── img1.PNG
│   │   └── img2.PNG
│   └── 你的文档.md
└── mkdocs.yml

第二步：修改图片路径 #

根据你的文档位置，选下面一种方式修改：

方式1：基于站点根目录的绝对路径（适配所有场景）

把HTML里的src改成/images/xxx.PNG，同时在mkdocs.yml里配置好你的GitHub Pages地址（比如site_url: https://你的用户名.github.io/仓库名/）。修改后的代码：

<div align="center">
 <img src="/images/img1.PNG">
 <img src="/images/img2.PNG">
 <figcaption>Fig1 (left), Fig2 (right)!</figcaption>
</div>

方式2：相对当前文档的路径（无需配置site_url）

如果你的markdown文件在docs的子文件夹里（比如docs/guides/教程.md），就用相对路径往上跳一级到images目录：

<div align="center">
 <img src="../images/img1.PNG">
 <img src="../images/img2.PNG">
 <figcaption>Fig1 (left), Fig2 (right)!</figcaption>
</div>

如果文档就在docs根目录，直接用./images/img1.PNG也可以。

第三步：验证 #

• 本地运行mkdocs serve预览，确认图片正常显示
• 提交代码到GitHub，等待Pages部署完成后检查图片加载状态

额外小技巧 #

要是用MkDocs的Markdown图片语法，路径规则也一样，示例：

![Fig1](/images/img1.PNG)
![Fig2](/images/img2.PNG)

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