GitHub Markdown文件中的相对链接

GitHub Markdown文件中的相对链接

技术背景

在GitHub上撰写Markdown文件时，为了让文档更加结构化和易于管理，常常需要在不同文档文件之间建立链接。绝对链接虽然可以解决链接问题，但当项目转移或分支切换时，绝对链接可能会失效。相对链接则可以在不同的查看环境（如GitHub网站和本地）都能正常工作，让文档更好地独立存在。

实现步骤

一般文件相对链接

  • 同一目录下的文件链接：如果要在当前Markdown文件中链接同一目录下的另一个文件，直接使用文件名即可。例如，在text.md文件中链接同一目录下的another_file.md，可以使用[链接文本](another_file.md)。
  • 子目录下的文件链接：如果目标文件在子目录中，使用相对路径即可。例如，目录结构为project/text.md和project/subpro/subtext.md，在text.md中链接subtext.md可以使用[链接文本](subpro/subtext.md)。
  • 上级目录及其他目录的文件链接：可以使用../来表示上级目录。例如，在subpro/subsubpro/subsubtext.md中链接上级目录subpro下的subtext.md，可以使用[链接文本](../subtext.md)；链接上级的上级目录中的text.md，可以使用[链接文本](../../text.md)。

以/开头的相对链接

当链接以/开头时，它是相对于仓库的根目录。例如，仓库根目录有一个myLib文件夹，要在Markdown文件中链接到该文件夹的README.md文件，可以使用[链接文本](/myLib/README.md)。

特殊情况处理

  • 目录名包含空格：如果目标目录名包含空格，需要使用%20替换空格。例如，目录结构为Top_dir/Cur_dir1/Dir A/README.md，在Top_dir/README.md中链接到Dir A下的README.md，可以使用[链接文本](Cur_dir1/Dir%20A/README.md)。
  • 链接到Wiki页面：要链接到GitHub仓库的Wiki页面，可以使用[链接文本](../../wiki/your-wiki-page)，两个../会移除/blob/master/，以仓库根目录为起点。

核心代码

一般文件链接示例

1
2
3
4
5
6
# 同一目录下的文件链接
[链接到同一目录文件](another_file.md)
# 子目录下的文件链接
[链接到子目录文件](subpro/subtext.md)
# 上级目录的文件链接
[链接到上级目录文件](../text.md)

以/开头的相对链接示例

1
[链接到根目录下的文件](/myLib/README.md)

目录名包含空格的链接示例

1
[链接到含空格目录下的文件](Cur_dir1/Dir%20A/README.md)

链接到Wiki页面示例

1
[链接到Wiki页面](../../wiki/your-wiki-page)

底部插入链接示例

1
2
3
This is [my linked text].

  [my linked text]: relative/path/in/repo/to/file.txt "Optional title for mouse hover"

最佳实践

  • 减少冗余信息：在Markdown文件中优先使用相对链接，避免使用绝对链接，这样即使项目在本地查看或在不同分支中查看，链接依然有效。
  • 链接注释和分组：如果同一个链接在文档中多次使用，可以将链接定义放在文档底部，这样可以减少文本中的混乱，提高文档的可读性。例如：
1
2
3
4
这是 [中文文档] 和 [日文文档] 的链接。

  [中文文档]: doc/cn/README.md "中文文档说明"
  [日文文档]: doc/jp/README.md "日文文档说明"
  • 多语言文档链接：在多语言文档项目中，利用相对链接方便地实现不同语言文档之间的相互链接。例如：
1
2
3
4
# 在/README.md中
[中文](doc/cn/README.md) | [日本語](doc/jp/README.md)
# 在/doc/cn/README.md中
[English](../../README.md) | [日本語](../jp/README.md)

常见问题

使用../的相对链接不生效

如果相对链接中使用了../却无法正常工作，可能是因为当前页面的URL不包含/blob/。解决方法是：如果当前页面URL不包含/blob/，则使用包含/blob/的完整URL来进行链接；不过除了顶层的/README.md，其他文件的查看页面URL通常已经包含/blob/，因此在这些文件中一般可以正常使用包含../的相对链接。

链接到目录失效

在Markdown文件中，链接文件通常可以正常工作，但链接目录可能会遇到问题。因为文件的URL以blob/<branch>/<path>/<fileName>开头，而目录的URL以tree/<branch>/<path>开头。不过GitHub有时会自动将某些相对路径转换为tree路径，但包含..的URL可能无法正常转换。如果要链接到目录，建议链接到目录下的某个文件。

链接样式和加载延迟

尽管链接功能本身不受影响，但大量复杂的链接或者服务器负载可能导致链接加载速度变慢。可以考虑优化文档结构，将链接集中管理，或者将无需实时加载的内容放到副文档中。同时，检查仓库本身的大小和资源引用情况，避免因资源过大造成加载延迟。

代码托管 > GitHub
#GitHub #Markdown #代码托管 #相对链接 #文件引用
GitHub Markdown文件中的相对链接
https://119291.xyz/posts/github-relative-link-in-markdown-file/
作者
ww
发布于
2025年5月30日
许可协议