Reference an image in: /sub1/【免费下载链接】mkdocsProject documentation with Markdown.项目地址: https://gitcode.com/gh_mirrors/mk/mkdocsRelative path[](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)Reference an image in: /Relative path[](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)解析结果 | 源文件位置 | 书写路径 | 实际命中目标 | 说明 | | --- | --- | --- | --- | | docs/sub1/sub1a/index.md | ../image.png | docs/sub1/image.png | 从 sub1a/ 向上一级进入 sub1/ | | docs/sub1/sub1a/index.md | ../../image.png | docs/image.png | 向上两级回到 docs/ 根 | 同一规则在 [sub1/index.md](https://link.gitcode.com/i/2b3abf8f3c5664c792d4dd329f078386)位于 docs/sub1/中体现为更浅的写法image.png 与 ./image.png 都命中 docs/sub1/image.png../image.png 命中 docs/image.png而 [docs/index.md](https://link.gitcode.com/i/1deb6b1115dc44ca6ee2f8e6d821dc09) 作为首页用 image.png 或 ./image.png 直接命中根目录图片。三个层级、同一套规则可以归纳为一句话**先定位当前 .md 文件再沿路径向上/向下走到目标**。 ### 相对路径会被重写为对最终 HTML 的相对路径 必须强调你在 Markdown 里写的相对路径并不会原样出现在生成的 HTML 中。MkDocs 会把它换算成**从当前页面 URL 到目标资源 URL 的相对路径**。原因在于默认开启的 use_directory_urls: true 使页面 URL 与源文件路径存在偏差 - 源文件 sub1/sub1a/index.md → 页面 URL sub1/sub1a/ - 源文件 sub1/sub1a/non-index.md → 页面 URL sub1/sub1a/non-index/ - 若关闭目录 URLuse_directory_urls: false→ 页面 URL 变为 sub1/sub1a/index.html、sub1/sub1a/non-index.html 单元测试 [page_tests.py](https://link.gitcode.com/i/a5f97e2e5f6e9583845c508aa8a9aa5a) 的 RelativePathExtensionTests 精确验证了这一换算。例如 test_relative_image_link_from_subpage当源文件为 sub2/non-index.md 时Markdown 中书写 [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)渲染出的 HTML 是 img altimage src../../image.png /见 [page_tests.py](https://link.gitcode.com/i/a5f97e2e5f6e9583845c508aa8a9aa5a#L968-L974)。再看链接用例 test_relative_html_link[link](https://link.gitcode.com/i/63f1f50d169288fad8f45a9436eb1852) 在目录 URL 模式下渲染为 a hrefnon-index/关闭目录 URL 后渲染为 a hrefnon-index.html见 [page_tests.py](https://link.gitcode.com/i/a5f97e2e5f6e9583845c508aa8a9aa5a#L799-L813)。这解释了为什么 MkDocs 允许你在 Markdown 中直接写 non-index.md 甚至不带扩展名而无需关心最终站点是 xxx/ 还是 xxx.html。 ## 绝对路径以 docs 目录为根路径以 / 开头 绝对路径的解析基准是 **docs_dir 的根**凡是以 / 开头的引用都会去掉前导斜杠后直接从 docs/ 下开始查找。它与相对路径的区别在于无论当前页面嵌套多深写法都保持一致。 继续看 [sub1a/index.md](https://link.gitcode.com/i/911cae19772a46a2eccbf1825d8dad6c) markdown ## Reference an image in: /sub1/ ### Absolute path [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f) [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f) ## Reference an image in: / ### Absolute path [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f) [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)解析结果书写路径实际命中目标/sub1/image.pngdocs/sub1/image.png/image.pngdocs/image.png同样的规则在 sub1/index.md/sub1/image.png与/image.png和 docs/index.md/image.png中完全一致。可以看到绝对路径的语义与当前页面所在层级彻底解耦这是它最大的优势——尤其适合在多级目录中引用共享资源如公共图片、Logo。绝对路径在最终 HTML 中同样被重写与相对路径一样Markdown 中的绝对路径也不会原样输出。MkDocs 会把/sub1/image.png换算成从当前页面到站点根下sub1/image.png的相对引用。换言之/是docs 根的语义标记而不是站点根/域名根。这保证了站点部署在任意子路径如 GitHub Pages 的项目页下时资源依然可用这也是 MkDocs 不直接输出/sub1/image.png这类写死根路径的原因。源码原理_RelativePathTreeprocessor如何重写路径上述所有行为都来自 MkDocs 渲染管线中的一个 Markdown Treeprocessormkdocs/structure/pages.py 中的_RelativePathTreeprocessor见 pages.py。它在每次页面render()时被注册进 Markdown 实例见 pages.py通过_register以优先级 0 挂载见 pages.py。其核心逻辑是run()遍历渲染后的 HTML 元素树只关心两类节点——a取href、img取src其余一律跳过见 pages.py。随后对每个 URL 调用path_to_url()见 pages.py处理流程大致如下外部链接直接放行带 scheme如https:或 netloc 的 URL 原样返回不做任何处理。绝对路径以/或\开头进入绝对链接校验分支——默认情况下它会继续解析目标且当validation.links.absolute_links被设置为relative_to_docs时/被显式解释为相对 docs 根。自引用仅含#anchor或查询串的链接原样保留并登记进links_to_anchors供锚点校验使用。相对路径解析通过_possible_target_uris()见 pages.py基于_target_uri()把当前源文件路径与书写路径拼接生成候选目标 URI——注意它会依次尝试多种写法直接路径、追加index.md/README.md、.html转.md这正是写non-index也能命中non-index.md的原因。在文件集合中查证候选 URI 能在files集合中找到目标文件就用utils.get_relative_url(target_file.url, self.file.url)计算当前页与目标页之间的相对 URL 并回写找不到则按validation配置输出对应级别的警告not_found、unrecognized_links等并保持原 URL 不动。因此相对还是绝对的语义差异实际发生在_possible_target_uris之前的分类环节而最终的 URL 换算统一收敛到目标文件 URL ↔ 当前页面 URL的相对化计算上。用测试与构建命令验证解析结果单元测试最直接的规则快照RelativePathExtensionTests见 page_tests.py将源码级行为固化为断言是学习路径解析规则的极佳参考。与本文主题强相关的用例包括test_relative_image_link_from_homepage首页中[](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)渲染为img altimage srcimage.png /目录 URL 开合均适用见 page_tests.pytest_relative_image_link_from_subpage子页面中../image.png被换算为../../image.png见 page_tests.pytest_relative_image_link_from_sibling兄弟页面non-index.md中image.png在目录 URL 模式下渲染为../image.png关闭后渲染为image.png见 page_tests.pytest_relative_html_link/test_relative_html_link_sub_index/test_relative_html_link_parent_index链接到.md文件、子目录index.md、父级../index.md时的 URL 换算见 page_tests.pytest_relative_html_link_with_encoded_space带空格文件名需 URL 编码file%20name.md。集成测试真实构建整套 subpages 项目仓库的集成测试入口 mkdocs/tests/integration.py 会对integration/下每个测试项目执行严格的构建命令见 integration.pymkdocs build -q -s --site-dir output # -q 静默-s 严格模式其中-s--strict会把所有警告升级为错误从而保证subpages项目中每一处图片引用都是真实有效的。你也可以在自己的文档项目上做同样的事# 在包含 mkdocs.yml 的项目根目录执行 mkdocs build --strict【免费下载链接】mkdocsProject documentation with Markdown.项目地址: https://gitcode.com/gh_mirrors/mk/mkdocs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Reference an image in: /sub1/【免费下载链接】mkdocsProject documentation with Markdown.项目地址: https://gitcode.com/gh_mirrors/mk/mkdocsRelative path[](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)Reference an image in: /Relative path[](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)解析结果 | 源文件位置 | 书写路径 | 实际命中目标 | 说明 | | --- | --- | --- | --- | | docs/sub1/sub1a/index.md | ../image.png | docs/sub1/image.png | 从 sub1a/ 向上一级进入 sub1/ | | docs/sub1/sub1a/index.md | ../../image.png | docs/image.png | 向上两级回到 docs/ 根 | 同一规则在 [sub1/index.md](https://link.gitcode.com/i/2b3abf8f3c5664c792d4dd329f078386)位于 docs/sub1/中体现为更浅的写法image.png 与 ./image.png 都命中 docs/sub1/image.png../image.png 命中 docs/image.png而 [docs/index.md](https://link.gitcode.com/i/1deb6b1115dc44ca6ee2f8e6d821dc09) 作为首页用 image.png 或 ./image.png 直接命中根目录图片。三个层级、同一套规则可以归纳为一句话**先定位当前 .md 文件再沿路径向上/向下走到目标**。 ### 相对路径会被重写为对最终 HTML 的相对路径 必须强调你在 Markdown 里写的相对路径并不会原样出现在生成的 HTML 中。MkDocs 会把它换算成**从当前页面 URL 到目标资源 URL 的相对路径**。原因在于默认开启的 use_directory_urls: true 使页面 URL 与源文件路径存在偏差 - 源文件 sub1/sub1a/index.md → 页面 URL sub1/sub1a/ - 源文件 sub1/sub1a/non-index.md → 页面 URL sub1/sub1a/non-index/ - 若关闭目录 URLuse_directory_urls: false→ 页面 URL 变为 sub1/sub1a/index.html、sub1/sub1a/non-index.html 单元测试 [page_tests.py](https://link.gitcode.com/i/a5f97e2e5f6e9583845c508aa8a9aa5a) 的 RelativePathExtensionTests 精确验证了这一换算。例如 test_relative_image_link_from_subpage当源文件为 sub2/non-index.md 时Markdown 中书写 [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)渲染出的 HTML 是 img altimage src../../image.png /见 [page_tests.py](https://link.gitcode.com/i/a5f97e2e5f6e9583845c508aa8a9aa5a#L968-L974)。再看链接用例 test_relative_html_link[link](https://link.gitcode.com/i/63f1f50d169288fad8f45a9436eb1852) 在目录 URL 模式下渲染为 a hrefnon-index/关闭目录 URL 后渲染为 a hrefnon-index.html见 [page_tests.py](https://link.gitcode.com/i/a5f97e2e5f6e9583845c508aa8a9aa5a#L799-L813)。这解释了为什么 MkDocs 允许你在 Markdown 中直接写 non-index.md 甚至不带扩展名而无需关心最终站点是 xxx/ 还是 xxx.html。 ## 绝对路径以 docs 目录为根路径以 / 开头 绝对路径的解析基准是 **docs_dir 的根**凡是以 / 开头的引用都会去掉前导斜杠后直接从 docs/ 下开始查找。它与相对路径的区别在于无论当前页面嵌套多深写法都保持一致。 继续看 [sub1a/index.md](https://link.gitcode.com/i/911cae19772a46a2eccbf1825d8dad6c) markdown ## Reference an image in: /sub1/ ### Absolute path [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f) [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f) ## Reference an image in: / ### Absolute path [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f) [](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)解析结果书写路径实际命中目标/sub1/image.pngdocs/sub1/image.png/image.pngdocs/image.png同样的规则在 sub1/index.md/sub1/image.png与/image.png和 docs/index.md/image.png中完全一致。可以看到绝对路径的语义与当前页面所在层级彻底解耦这是它最大的优势——尤其适合在多级目录中引用共享资源如公共图片、Logo。绝对路径在最终 HTML 中同样被重写与相对路径一样Markdown 中的绝对路径也不会原样输出。MkDocs 会把/sub1/image.png换算成从当前页面到站点根下sub1/image.png的相对引用。换言之/是docs 根的语义标记而不是站点根/域名根。这保证了站点部署在任意子路径如 GitHub Pages 的项目页下时资源依然可用这也是 MkDocs 不直接输出/sub1/image.png这类写死根路径的原因。源码原理_RelativePathTreeprocessor如何重写路径上述所有行为都来自 MkDocs 渲染管线中的一个 Markdown Treeprocessormkdocs/structure/pages.py 中的_RelativePathTreeprocessor见 pages.py。它在每次页面render()时被注册进 Markdown 实例见 pages.py通过_register以优先级 0 挂载见 pages.py。其核心逻辑是run()遍历渲染后的 HTML 元素树只关心两类节点——a取href、img取src其余一律跳过见 pages.py。随后对每个 URL 调用path_to_url()见 pages.py处理流程大致如下外部链接直接放行带 scheme如https:或 netloc 的 URL 原样返回不做任何处理。绝对路径以/或\开头进入绝对链接校验分支——默认情况下它会继续解析目标且当validation.links.absolute_links被设置为relative_to_docs时/被显式解释为相对 docs 根。自引用仅含#anchor或查询串的链接原样保留并登记进links_to_anchors供锚点校验使用。相对路径解析通过_possible_target_uris()见 pages.py基于_target_uri()把当前源文件路径与书写路径拼接生成候选目标 URI——注意它会依次尝试多种写法直接路径、追加index.md/README.md、.html转.md这正是写non-index也能命中non-index.md的原因。在文件集合中查证候选 URI 能在files集合中找到目标文件就用utils.get_relative_url(target_file.url, self.file.url)计算当前页与目标页之间的相对 URL 并回写找不到则按validation配置输出对应级别的警告not_found、unrecognized_links等并保持原 URL 不动。因此相对还是绝对的语义差异实际发生在_possible_target_uris之前的分类环节而最终的 URL 换算统一收敛到目标文件 URL ↔ 当前页面 URL的相对化计算上。用测试与构建命令验证解析结果单元测试最直接的规则快照RelativePathExtensionTests见 page_tests.py将源码级行为固化为断言是学习路径解析规则的极佳参考。与本文主题强相关的用例包括test_relative_image_link_from_homepage首页中[](https://link.gitcode.com/i/0f1c98ec0bfde43bfe9c24de0fe0200f)渲染为img altimage srcimage.png /目录 URL 开合均适用见 page_tests.pytest_relative_image_link_from_subpage子页面中../image.png被换算为../../image.png见 page_tests.pytest_relative_image_link_from_sibling兄弟页面non-index.md中image.png在目录 URL 模式下渲染为../image.png关闭后渲染为image.png见 page_tests.pytest_relative_html_link/test_relative_html_link_sub_index/test_relative_html_link_parent_index链接到.md文件、子目录index.md、父级../index.md时的 URL 换算见 page_tests.pytest_relative_html_link_with_encoded_space带空格文件名需 URL 编码file%20name.md。集成测试真实构建整套 subpages 项目仓库的集成测试入口 mkdocs/tests/integration.py 会对integration/下每个测试项目执行严格的构建命令见 integration.pymkdocs build -q -s --site-dir output # -q 静默-s 严格模式其中-s--strict会把所有警告升级为错误从而保证subpages项目中每一处图片引用都是真实有效的。你也可以在自己的文档项目上做同样的事# 在包含 mkdocs.yml 的项目根目录执行 mkdocs build --strict【免费下载链接】mkdocsProject documentation with Markdown.项目地址: https://gitcode.com/gh_mirrors/mk/mkdocs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
