Test sub pages and referencing images【免费下载链接】mkdocsProject documentation with Markdown.项目地址: https://gitcode.com/gh_mirrors/mk/mkdocsReference an image in: /Relative path[](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9)Relative path 2[](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9)Absolute path[](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9)这里展示了引用根目录图片 image.png 的三种写法 | 写法 | 类型 | 语义 | | --- | --- | --- | | [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) | 相对路径 | 相对于当前 .md 文件所在目录 | | [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) | 相对路径显式 ./ | 与上者等价显式声明当前目录 | | [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) | 绝对路径 | 以 / 开头默认按站点根路径理解 | **关键知识点image.png 与 ./image.png 完全等价**。MkDocs 在解析时会对路径做规范化posixpath.normpath多余的 ./ 会被合并掉。而 /image.png 则走完全不同的分支——默认情况下 MkDocs 会将其原样保留并告警这正是 [mkdocs/structure/pages.py](https://link.gitcode.com/i/a98e29937ef5e44c7c964b9663ce64bc) 中 path_to_url 方法的处理逻辑我们会在第四节详细拆解。 ## 三、子页面层级递进同一写法在不同深度的真实解析 subpages 项目的精髓在于**相同的写法在不同深度的页面中指向不同的文件**。下面按目录层级逐一说明。 ### 3.1 一层子目录sub1/index.md 文件 [sub1/index.md](https://link.gitcode.com/i/19b5c695f92d9e10820a4f729ec074bb) 展示了两个方向的引用 markdown ## Reference an image in: /sub1/ ### Relative path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 指向 docs/sub1/image.png同目录 ### Relative path 2 [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 同上等价写法 ### Absolute path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 指向 docs/sub1/image.png ## Reference an image in: / ### Relative path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 指向 docs/image.png父目录 ### Absolute path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 指向 docs/image.pngdocs 根要点在本目录内引用本目录图片直接写image.png即可无需./前缀引用父目录docs/的图片相对写法是../image.png绝对写法/sub1/image.png与相对写法image.png指向同一个物理文件——绝对路径以docs_dir即docs/为根。3.2 两层子目录sub1/sub1a/index.md文件 sub1/sub1a/index.md 将路径层级推到了最深处## Reference an image in: /sub1/ ### Relative path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 指向 docs/sub1/image.png上一层 ### Absolute path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 同上绝对写法 ## Reference an image in: / ### Relative path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 指向 docs/image.png跨两级 ### Absolute path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 同上绝对写法这里出现了著名的../../跨级写法从sub1/sub1a/回到docs/根目录相对路径需要向上跳两级。绝对路径则不受层级影响——/image.png无论在首页、sub1/还是sub1/sub1a/中书写都稳定指向docs/image.png。这是绝对路径在深层目录中的最大优势写法恒定、不随页面位置漂移。3.3 兄弟目录互引sub2/index.md文件 sub2/index.md 演示了引用兄弟目录而非祖先目录图片的写法## Reference an image in: /sub1/ ### Relative path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 指向 docs/sub1/image.png ### Absolute path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 同上 ## Reference an image in: / ### Relative path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 指向 docs/image.png ### Absolute path [](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9) # 同上从sub2/引用sub1/的图片需要先..回到docs/根再进入sub1/即../sub1/image.png而绝对写法仍是稳定不变的/sub1/image.png。可以看出相对路径的写法取决于当前页面位置与目标文件位置之间的相对关系绝对路径则只取决于目标文件在docs_dir中的位置。3.4 汇总对照表页面位置引用 docs/image.png引用 docs/sub1/image.pngdocs/index.mdimage.png//image.pngsub1/image.png//sub1/image.pngdocs/sub1/index.md../image.png//image.pngimage.png//sub1/image.pngdocs/sub1/sub1a/index.md../../image.png//image.png../image.png//sub1/image.pngdocs/sub2/index.md../image.png//image.png../sub1/image.png//sub1/image.png同一张sub1/image.png在四个位置的相对写法分别为sub1/image.png、image.png、../image.png、../sub1/image.png而绝对写法始终是/sub1/image.png。这正是 MkDocs 的_RelativePathTreeprocessor需要在构建时逐页重写 URL 的根本原因。四、源码级原理_RelativePathTreeprocessor如何重写图片 URL理解了应该怎么写之后来看 MkDocs 如何做到。在页面渲染阶段mkdocs/structure/pages.py中定义了_RelativePathTreeprocessor类pages.py#L346-L519它是一个注册在 Markdown 解析管线里的 treeprocessor注册名relpath优先级 0。其run方法遍历渲染后的 HTML 元素树def run(self, root: etree.Element) - etree.Element: Update urls on anchors and images to make them relative. for element in root.iter(): if element.tag a: key href elif element.tag img: key src else: continue url element.get(key) assert url is not None new_url self.path_to_url(url) element.set(key, new_url) return root也就是说a的href与img的src使用同一套路径解析逻辑——Markdown 文档中写的链接超链接和图片引用alt在渲染后都会被这个处理器统一重写这正是为什么链接文档与引用图片的路径规则完全一致。随后path_to_urlpages.py#L419-L516按以下顺序裁决外部链接带scheme或netloc如https://...直接原样返回绝对链接以/或\开头默认打一条validation.links.absolute_links级别的告警was left as is并原样保留——除非配置了relative_to_docs见第五节纯锚点/查询链接#hash、?query原样返回相对链接先通过_possible_target_uris推测目标文件在docs_dir中的src_uri依次尝试原路径、index.md、README.md、去掉.html等猜测再到Files集合中查找真实文件找到目标文件后调用utils.get_relative_url(target_file.url, self.file.url)计算当前页面到目标文件的相对 URL最后用urlunsplit拼接并写回src属性。关键在于第 5 步无论作者在源码里写的是image.png、../image.png还是./image.pngMkDocs 都会先解析出目标文件再基于目标页面的最终 URL 与当前页面的最终 URL 重新计算相对路径。因此即使use_directory_urls开启、页面 URL 形如sub1/而非sub1/index.html生成的img src也会被自动修正为正确的相对位置不会因目录式 URL 而 404。4.1use_directory_urls的影响配置项use_directory_urls定义于 mkdocs/config/defaults.py#L99-L104默认值为Trueuse_directory_urls c.Type(bool, defaultTrue) If True, use page_name/index.html style files with hyperlinks to the directory. If False, use page_name.html style file with hyperlinks to the file. True generates nicer URLs, but False is useful if browsing the output on a filesystem.True默认页面 URL 采用目录式如sub1/、sub1/sub1a/生成的图片相对路径往往需要多出../False页面 URL 采用平铺文件式如sub1/index.html、sub1/sub1a/index.html相对路径计算随之变化。由于重写逻辑统一基于目标页面的最终 URL两种模式下 MkDocs 都能生成自洽的相对路径。use_directory_urls: False特别适合直接把site/输出目录丢到本地文件系统浏览的场景。五、绝对路径的默认行为与relative_to_docs配置前面多次提到以/开头的绝对路径默认并不会按docs_dir根目录解析。这一行为的历史背景与现行配置在官方文档 docs/user-guide/configuration.md#validation-of-absolute-links 中有完整说明历史上在 Markdown 中 MkDocs 只识别指向另一个物理*.md文档或媒体文件的相对链接这是值得遵循的好约定因为这样源码页面无需 MkDocs 也能自由浏览例如在 GitHub 上。而绝对链接要么被原样保留往往达不到预期效果要么在较新版本中被告警。如果你不喜欢总是写相对链接现在可以选择开启绝对链接并让它正确工作。对应到代码即 pages.py#L428-L432elif url.startswith((/, \\)): # Absolute link. absolute_link self.config.validation.links.absolute_links if absolute_link is not _AbsoluteLinksValidationValue.RELATIVE_TO_DOCS: warning_level absolute_link warning fDoc file {self.file.src_uri} contains an absolute link {url}, it was left as is.默认的validation.links.absolute_links取值为info见 mkdocs/config/defaults.py#L28-L32 中_AbsoluteLinksValidation的定义此时绝对路径被原样保留并产生一条 info 级日志。注意这意味着[](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9)在默认配置下不会指向docs/image.png而是指向站点根路径/image.png——若站点部署在域名根路径下或许碰巧可用一旦部署到子路径就会失效这也是官方文档建议开启relative_to_docs的原因。自 MkDocs 1.6 起可以将validation.links.absolute_links设为特殊值relative_to_docs让所有/开头的链接按docs_dir根目录解析validation: links: absolute_links: relative_to_docs anchors: warn unrecognized_links: warn开启后/dir2/bar.md会被解析为docs/dir2/bar.md并参与与其他相对链接相同的校验且HTML 输出时仍会被改写为相对路径保证站点部署在任何位置都能可靠工作。此时任意页面例如dir1/foo.md都可以用link替代原先唯一的正确写法link。需要强调的是默认配置下这一功能并未开启绝对链接默认仍是跳过并告警。六、测试验证subpages 项目在测试体系中的角色subpages项目不是孤立的示例它同时被两层测试引用构成了行为规范的实证依据。6.1 单元测试page_tests.pymkdocs/tests/structure/page_tests.py 在文件头部将DOCS_DIR直接指向 subpages 的 docs 目录L16-L18DOCS_DIR os.path.join( os.path.abspath(os.path.dirname(__file__)), .., integration, subpages, docs )其中RelativePathExtensionTests类专门测试图片路径重写L957-L990def test_relative_image_link_from_homepage(self): for use_directory_urls in True, False: self.assertEqual( self.get_rendered_result( use_directory_urlsuse_directory_urls, content[](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9), files[index.md, image.png], ), img altimage srcimage.png /, # no opening ./ ) def test_relative_image_link_from_subpage(self): self.assertEqual( self.get_rendered_result( content[](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9), files[sub2/non-index.md, image.png] ), img altimage src../../image.png /, ) def test_relative_image_link_from_sibling(self): self.assertEqual( self.get_rendered_result( content[](https://link.gitcode.com/i/9a3be0cc8f8462b1b11ae6c3407e4fe9), files[non-index.md, image.png] ), img altimage src../image.png /, )这些断言精确量化了前面表格中的行为首页index.md引用image.png输出srcimage.png无多余的./验证了规范化逻辑子页面sub2/non-index.md引用../image.png指docs/image.png由于non-index.md的目录式 URL 是sub2/non-index/重写后变成../../image.png同级页面non-index.md引用同目录image.png重写为../image.png。6.2 集成测试integration.pymkdocs/tests/integration.py 是一个构建型集成测试它会遍历mkdocs/tests/integration/下的每个项目目录用mkdocs build -q -s --site-dir 输出目录以严格模式-s/--strict真实构建每个项目L61-L69log.debug(Building test projects.) for project in os.listdir(TEST_PROJECTS): project_dir os.path.join(TEST_PROJECTS, project) if not os.path.isdir(project_dir): continue log.debug(fBuilding test project: {project}) out os.path.join(output, project) command [*base_cmd, out] subprocess.check_call(command, cwdproject_dir)-s--strict会将所有warn级日志升级为错误因此subpages项目若存在任何指向不存在的图片、或产生未预期告警的路径构建就会直接失败。这从测试层面保证了文档中那些../、../../、/sub1/image.png的写法在当前 MkDocs 源码版本下确实能全部解析成功。你可以在仓库根目录自行复现验证python -m mkdocs.tests.integration # 或单独构建该示例项目 mkdocs build -s --site-dir /tmp/subpages-site mkdocs/tests/integration/subpages【免费下载链接】mkdocsProject documentation with Markdown.项目地址: https://gitcode.com/gh_mirrors/mk/mkdocs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考