Markdown 文件中的 GitHub 相对链接

Question

有没有办法创建 URL 锚点 ，从 Markdown 文件内链接到同一存储库和分支内的另一个文件（也称为相对于当前分支的链接）？

例如，在主分支中，我有一个 README.md 文件，我希望执行以下操作：

# My Project
is really really cool. My Project has a subdir named myLib, see below.

## myLib documentation
see documentation [here](myLib/README.md)

这将允许我从一个 .md 链接到同一分支内的另一个 .md，而不必担心我是哪个分支in （避免必须执行包含 github.com 分支名称的绝对 URL）。

这是我的意思的一个有效示例：

1. GOTO http://github.com/rynop/testRel，链接不起作用。
2. 转到 http://github.com/rynop/testRel/blob/master/README.md ，链接有效。

这是预期的，因为此时起始 URL 位于分支中。现在我如何让它在存储库根目录的 README.md 中获取当前分支？

更新：我针对此功能请求针对 GitHub 提出了问题。

Answer 1

16 个月后2013 年 1 月 30 日更新：

GitHub 博客文章标记文件中的相对链接：

从今天开始，GitHub 支持标记文件中的相对链接。
现在，您可以直接在不同的文档文件之间链接，无论您是在 GitHub 本身上查看文档，还是在本地使用不同的标记渲染器查看文档。

您想要链接定义及其工作原理的示例吗？这是给你的一些 Markdown。
而不是绝对链接：

[链接](https://github.com/user/repo/blob/branch/other_file.md)

...您可以使用相对链接：

[相对链接](other_file.md)
[相对链接](path%20with%20spaces/other_file.md)

我们将确保它链接到 user/repo/blob/branch/other_file.md。

如果您使用的是[解决方法链接](repo/blob/master/other_file.md)等解决方法，则必须更新文档才能使用新语法。

这也意味着您的文档现在可以轻松独立，而无需始终指向 GitHub。

Marcono1234 添加了 评论

也很有用：当链接以 / 开头时，它是相对于存储库的根目录的（无论 markdown 文件是否嵌套在子目录中）

---

2011 年 12 月 20 日更新：

GitHub 标记问题 84 目前已由 technoweenie，评论如下：

我们尝试为此添加 标记，但这会导致网站上其他相关链接出现问题。

---

2011 年 10 月 12 日：

如果您查看 的原始源代码Markdown 本身的 >README.md（！），似乎不支持相对路径。
您会发现如下参考：

[r2h]: http://github.com/github/markup/tree/master/lib/github/commands/rest2html
[r2hc]: http://github.com/github/markup/tree/master/lib/github/markups.rb#L13

---

如 InvisibleWolf 的 回答，如果目标链接是一个目录并且有空格，那么每个空格都需要使用%20。

Answer 2

例如，您有如下所示的存储库：

project/
    text.md
    subpro/
       subtext.md
       subsubpro/
           subsubtext.md
       subsubpro2/
           subsubtext2.md

text.md 中 subtext.md 的相对链接可能如下所示：

[this subtext](subpro/subtext.md)

subsubtext 的相对链接。 text.md 中的 md 可能如下所示：

[this subsubtext](subpro/subsubpro/subsubtext.md)

subsubtext.md 中 subtext.md 的相对链接可能如下所示:

[this subtext](../subtext.md)

相对链接subsubtext.md 中的 subsubtext2.md 可能如下所示：

[this subsubtext2](../subsubpro2/subsubtext2.md)

subsubtext.md 中 text.md 的相对链接> 可能看起来像这样：

[this text](../../text.md)

Answer 3

GitHub 可以用最少的工作让这一切变得更好。这是一个解决方法。

我认为你想要一些更像

[Your Title](your-project-name/tree/master/your-subfolder)

或指向自述文件本身的东西

[README](your-project-name/blob/master/your-subfolder/README.md)

Answer 4

截至 2013 年 1 月 31 日，Github markdown 支持文件的相对链接 。

[a relative link](markdown_file.md)

但是，此评论线程中讨论了一些缺陷。

作为替代方案，您可以使用 Gitdown 构建 存储库的完整 URL 甚至让它们了解分支，例如

{"gitdown": "gitinfo", "name": "url"} // https://github.com/gajus/gitdown
{"gitdown": "gitinfo", "name": "branch"} // master

Gitdown 是一个 GitHub markdown 预处理器。它简化了与维护 GitHub 存储库文档页面相关的常见任务，例如生成目录（包括变量）、生成 URL 以及在处理输入时获取有关存储库本身的信息。 Gitdown 与您的构建脚本无缝集成。

我是 Gitdown 库的作者。

Answer 5

我发现适用于相对文件夹的内容：

[link text](subfolder/subsubfolder/relevantfolder/)

其中相关文件夹是您尝试链接到的文件夹。最终文件夹名称后需要斜杠。我尝试在路径中包含项目名称和树/主目录以及之前答案中建议的其他内容，这会导致不存在的页面错误。子文件夹是整个存储库项目文件夹中的一个文件夹。

因此，文件链接的形式如下：

[link text](subfolder/subsubfolder/relevantfolder/index.html)

如果所需的文件不在任何文件夹或子文件夹中，则链接很简单：

[link text](README.md)

例如 README 文件不在任何子文件夹中，因此这可能是您用于自述文件。

Answer 6

只是想添加此内容，因为如果目标链接是名称中包含空格的目录，则上述解决方案都不起作用。如果目标链接是一个目录并且有空格，那么即使使用 \ 转义空格也不会在 Github 上呈现该链接。唯一对我有用的解决方案是对每个空间使用 %20 。

例如：如果目录结构是这样的

Top_dir
|-----README.md
|-----Cur_dir1
      |----Dir A
           |----README.md
      |----Dir B
           |----README.md

要链接到 Top_dir 中 README.md 中的 Dir A，您可以执行以下操作：

[Dir 1](Cur_dir1/Dir%20A)

Answer 7

您可以链接到文件，但不能链接到文件夹，请记住，Github 会在相对链接之前添加 /blob/master/ （文件夹缺少该部分，因此无法链接，也无法链接） HTML 标签或 Markdown 链接）。

因此，如果我们在 myrepo/src/Test.java 中有一个文件，它将具有如下 url：

https://github.com/WesternGun/myrepo/blob/master/src/Test.java

为了在自述文件中链接它，我们可以使用：

[This is a link](src/Test.java)

或： < a href="src/Test.java">这是一个链接。

（我猜，master 代表 master 分支，当文件位于另一个分支时它会有所不同。）

Answer 8

这个问题已经很老了，但它似乎仍然很重要，因为将 readme.md 中的相关引用放到 Github 上的 wiki 页面并不容易。

我玩了一下，这个相对链接似乎工作得很好：

[Your wiki page](../../wiki/your-wiki-page)

两个 .. / 将删除 /blob/master/ 并使用您的基础作为起点。不过，我还没有在 Github 之外的其他存储库上尝试过这个（可能存在兼容性问题）。

Answer 9

您可以通过 使用存储库根目录中的相对 URL。假设您的存储库名为 testRel，请将以下内容放入 testRel/README.md 中：

# My Project
is really really cool. My Project has a subdir named myLib, see below.

## myLib docs
see documentation:
    * <a href="testRel/myLib">myLib/</a>
    * <a href="testRel/myLib/README.md">myLib/README.md</a>

Answer 10

在 .md 文件中，当您想要创建指向与相同 项目文件夹 或基于 URL 的链接相关的任何相关文件的链接时：

1. 现有文件关联：

在.md文件中添加在[]框中显示名称，然后打开()在此框中添加/ 之后，它将自动获取您选择文件夹的所有现有文件夹名称形式，然后添加“/”，它将显示内部文件或“文件夹”。这意味着它将自动获取路径，最后创建您的 URL。

示例：

[Enter Showing Name](/users/4000266/heysushil)

这一行显示如下：
输入显示名称

2. 在 .md 文件中添加 URL

遵循相同的过程，仅使用 URL 更改 () 框路径，如下所示：

 [HeySushil - YouTube](https://youtube.com/heysushil)

这看起来像 HeySushil - YouTube

注意：记住在 () 框中添加 / 后无需手动添加强制，它将自动获取所有现有的 文件夹 和 文件。

Answer 11

我不确定我是否在这里看到这个选项。您只需在存储库中创建一个 /folder 并直接使用它：

[a relative link](/folder/myrelativefile.md)

不需要 blob、树或存储库名称，并且它的工作方式就像一个魅力。

Answer 12

如果您想要 GitHub 上 wiki 页面的相对链接，请使用以下内容：

Read here: [Some other wiki page](path/to/some-other-wiki-page)

如果您想要存储库中文件的链接，比方说，引用某些头文件，并且 wiki 页面位于 wiki 的根目录，使用这个：

Read here: [myheader.h](../tree/master/path/to/myheader.h)

最后一个的基本原理是用“../”跳过“/wiki”路径，并转到存储库树中的主分支，而不指定存储库名称，该名称将来可能会发生变化。

Answer 13

Markdown 文件中 Github 目录链接的行为可能会造成一些麻烦。

所有文件的 url 均以 blob 开头，

blob/<branch>/<path>/<fileName>

而目录的 url 均以 tree 开头：

tree/<branch>/<path>

因此，目录的相对链接不应该起作用。它指向一个以 blob 开头的 URL。神奇的是，Github 自动将一些相对路径更改为树路径。不幸的是，不是包含“..”的网址，

我调查了一些时间来检查 https://github.com/fluencecodes/GitSamples-GIT/tree/github-readme-links。

Answer 14

只需遵循以下格式即可。

[TEXT TO SHOW](actual URL to navigate)

Answer 15

以下是我在 github 的 .md 文件中找到的相对链接：

1. 没有 ../ 的相对链接（又名。链接到同一级别的文件，或在子目录），似乎总是有效。
2. 仅当您已位于 url 包含子字符串 /blob/ 的页面中时，包含 ../ 的相对链接才有效。
   • 否则需要使用包含 /blob/ 的完整网址进行链接。
3. 实际上，除了顶层 /README.md 之外，当查看任何其他文件时，它们的 url 已经包含 /blob/ 。
   • 因此，您可能始终可以在文件中使用包含 ../ 的相对链接，/README.md 除外。
   • 但是 /README.md 位于顶层，因此它不需要包含 ../ 的相对链接。
   • 因此，您永远不需要完整路径链接（包含 github 域）来链接到同一 github 存储库中的文件。

---

示例（多语言文档之间的链接）

• 在/README.md中，可以使用不带../的相对链接。

  [中文](doc/cn/README.md) |
  [日本语](doc/jp/README.md)
  

• 在/doc/cn/README.md中，由于我们查看时，url中已经包含/blob/，因此可以使用的相对链接../.

  [英文](../../README.md) |
  [日本语](../jp/README.md)
  

（顺便说一句，示例来自此 git-merge-流程存储库。）

Answer 16

接受的答案引用：

也很有用：当链接以 / 开头时，它是相对于存储库的根目录的（无论 markdown 文件是否嵌套在子目录中）

......这是我需要的，但这没有提供示例。

以下是基于 OP 链接的存储库的示例。

使用存储库：github.com/rynop/testRel...

• 对于目录：https://github.com/rynop/testRel/tree/master/myLib

  • 使用：/myLib

• 对于文件：https:// /github.com/rynop/testRel/blob/master/myLib/README.md

  • 使用：/myLib/README.md

---

注意，目录 URL构建在 tree/master/ 上，而文件 URL 构建在 blob/master/ 上。

那没关系。 GitHub 会整理出来的。 （您甚至可以将 tree 与 blob 互换，并且 URL 将重定向它们需要去的地方。）

只需从 / 在 tree/master/ 或 blob/master/ 的末尾，您的相对链接应该可以工作。

Answer 17

您还可以在底部插入链接（相对或绝对）以减少文本混乱。
对于重复链接来说，它也是一个不错的选择。

This is [my linked text].

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

这是我的链接文本 。