SVG 排错清单¶

注释不能嵌套

<!-- <!-- 内层 --> --> 是非法的。如果原文件里已有注释，二分时不要用包裹式注释，改成直接删除目标段落（记得先备份）。

id 是全局唯一的

SVG 里 id 在整个文档内必须唯一。如果内联了多张 SVG 到同一个页面，而它们用了相同的 id（比如都叫 arrow），就会产生冲突——浏览器只认第一个，后面的引用会指向错误的对象。 做法：内联多张 SVG 时，给每张图的 id 加前缀，例如 fig1-arrow、fig2-arrow。

在 MkDocs 里引用本地图片，优先用 ![](path) 而非裸 <img>

本站多次踩过这个坑：裸 HTML <img src="assets/x.svg"> 的 src 不会被 MkDocs 重写相对路径，而 use_directory_urls（默认 true）会让每篇页面变成自己的目录。结果——

• 页面在顶级目录（如 SVG/index.md → /SVG/）时，assets/ 碰巧解析正确，图显示正常；
• 同一张图放在子页面（如 SVG/改图的六种常见手术.md → /SVG/改图的六种常见手术/）时，assets/ 被解析到不存在的 /SVG/改图的六种常见手术/assets/，直接 404。

首页正常、子页挂掉，正是这个特征。正确写法：

![图注](assets/x.svg){: style="max-width:680px;width:100%;height:auto"}

MkDocs 会按每篇页面的实际深度自动重写路径（子页生成 ../assets/x.svg、首页生成 assets/x.svg），无论页面嵌套多深都不会错；GitHub Pages 子路径部署也安全，无需写死绝对路径。

样式用 attr_list 的 {: style="..."} 携带（Material 默认开启 attr_list 扩展），等价原先 <img> 上的 style 属性。

启用 wikilink 插件后，纯文件名链接会被全局匹配（很隐蔽）

许多 MkDocs 站点会装 wikilink 类插件（如 mkdocs-roamlinks-plugin），用来支持 [[双括号]] 写法。这类插件通常会把不带目录前缀的纯文件名链接也纳入"按文件名全局匹配"的逻辑。

后果：](index.md) 这种写法，本意是"当前目录下的 index.md"，但插件会在整个 docs 目录里找所有叫 index.md 的文件——站点里往往有十几个——然后匹配到其中一个，最终链接指向一个毫不相关的页面。构建不报错、页面渲染正常，只是链接是错的，非常隐蔽。

判断方法：打开构建产物的 HTML，检查该链接的 href 是否指向了预期之外的目录。

规避办法：

<!-- 可能被误匹配（index.md 是重名文件） -->
[← 返回索引](./index.md)

<!-- 站点绝对路径（推荐，最稳） -->
[← 返回索引](/分类/子分类/)

<!-- 带目录前缀（同样能绕开纯文件名匹配） -->
[← 返回索引](../子分类/index.md)

文件名在站内唯一时（如 改图的六种常见手术.md）不受影响，出问题的基本都是 index.md 这类通用名。