Markdown 文件中的 GitHub 相对链接答案

【问题标题】：GitHub relative link in Markdown fileMarkdown 文件中的 GitHub 相对链接
【发布时间】：2011-11-30 23:52:51
【问题描述】：

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

例如，在 master 分支中，我有一个 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 链接到另一个，而不必担心我在哪个分支（避免使用包含 github.com 分支名称的绝对 URL）。

这是我的意思的一个工作示例：

转到http://github.com/rynop/testRel，链接失效。
转到http://github.com/rynop/testRel/blob/master/README.md，链接有效。

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

更新：我针对此功能请求在 GitHub 上打开了 issue。

【问题讨论】：

终于：现在支持相对链接！我已经更新了我的答案:)
您可以在这个问题中找到一些解决方案：stackoverflow.com/questions/40422790/…

标签： github markdown github-flavored-markdown

【解决方案1】：

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

GitHub Blog Post Relative links in markup files:

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

您想要链接定义的示例以及它们如何工作？这是给你的一些 Markdown。
而不是绝对链接：
[a link](https://github.com/user/repo/blob/branch/other_file.md)
…您可以使用相对链接：
[a relative link](other_file.md)
[a relative link](path%20with%20spaces/other_file.md)
我们会确保它链接到user/repo/blob/branch/other_file.md。

如果您使用像 [a workaround link](repo/blob/master/other_file.md) 这样的解决方法，则必须更新您的文档以使用新语法。

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

Marcono1234 添加the comments

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

2011 年 12 月 20 日更新：

GitHub markup issue 84目前已被technoweenie关闭，附注：

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

2011 年 10 月 12 日：

如果您查看 Markdown 本身的 raw source of the 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的answer中所述，如果目标链接是一个目录并且它有空间，那么你需要为每个空间使用%20。

【讨论】：

嗯.. 我可以创建一个相对 URL（尝试 [link] someDir/README.md，它会成为一个锚点） - 但我想要一个 github 分支感知相对链接，例如：myRepo/tree/ /pathToMd.md。我可能会在 github.com 上打开一个功能请求
不。在此处查看完整示例github.com/rynop/testRel。我可以做一个指定分支的相对链接，但这违背了我首先要做的事情的目的。如果我从一个子目录中的 .md 链接到另一个子目录，我认为它可以很好地处理相对链接。从 repo 根目录中的 .md 链接时出现问题。
相关：对于从一个 wiki 页面链接到另一个，[Welcome](./wiki/Hello) 有效，其中 Hello 是同一 repo 中的另一个 wiki 页面。
这适用于常规 wiki 页面，但如果您添加 _Sidebar.md 文件，则 wiki 主页上的链接解析方式与其他页面不同。我在这里尝试了一切，但没有运气。到目前为止，我唯一想到的就是使用 2 个不同的 _Sidebar.md 文件并将这些文件组织到子目录中。
也有用：当链接以/开头时，它是相对于存储库的根目录（不管markdown文件是否嵌套在子目录中）。

【解决方案2】：

您可以通过<a href=""> 使用来自您的repo 根目录的相对URL。假设您的 repo 名为 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>

【讨论】：

这不是有效的 md 语法

【解决方案3】：

GitHub 可以通过最少的工作使这变得更好。这是一个解决方法。

我想你想要的东西更像

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

或指向自述文件本身

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

【讨论】：

是的，这就是我今天所做的。我不想将分支信息烘焙到链接中。它应该是相对的。

【解决方案4】：

我不确定我是否在此处看到此选项。您可以在您的存储库中创建一个/folder 并直接使用它：

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

不需要 blob、树或存储库名称，它就像一个魅力。

【讨论】：

你会认为这是显而易见的方法，但它对我不起作用。

【解决方案5】：

截至 2013 年 1 月 31 日 Github markdown supports relative links to files。

[a relative link](markdown_file.md)

但是，discussed in this comment thread 存在一些不足。

作为替代方案，您可以使用Gitdown 来构造full URLs to the repository，甚至可以让它们感知分支，例如

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

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

我是 Gitdown 库的作者。

【讨论】：

@Thomas 这是 Stack Overflow 使用条款的一部分吗？如果是，请分享一个链接。我很想知道这种要求背后的动机。
“发布好的、相关的答案，如果某些（但不是全部）恰好与您的产品或网站有关，那没关系。但是，您必须在答案中披露您的从属关系。” stackoverflow.com/help/behavior
有人会认为这属于 Stack Overflow 极力避免的元信息，即促进离题讨论。

【解决方案6】：

如果您想要一个指向 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”路径，并在不指定存储库名称的情况下转到存储库树中的主分支，这可能会在未来发生变化。

【讨论】：

【解决方案7】：

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

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

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

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

【讨论】：

【解决方案8】：

例如，您有一个如下所示的 repo：

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

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

[this subtext](subpro/subtext.md)

text.md 中到 subsubtext.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)

【讨论】：

我发现了一件事，链接是区分大小写的，这是我没想到的。
如果我的目录中有空格怎么办？
@Andy 那是 Linux 的东西，文件名区分大小写

【解决方案9】：

只是想添加它，因为如果目标链接是名称中带有空格的目录，则上述解决方案均无效。如果目标链接是一个目录并且它有空间，那么即使使用 \ 转义空间也不会在 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)

【讨论】：

【解决方案10】：

您可以链接到文件，但不能链接到文件夹，请记住，Github 会在您的相对链接之前添加 /blob/master/（并且文件夹缺少该部分，因此它们无法链接，无论是 HTML <a> 标签或降价链接）。

所以，如果我们在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">This is a link</a>。

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

【讨论】：

【解决方案11】：

请遵循以下格式。

[TEXT TO SHOW](actual URL to navigate)

【讨论】：

它没有回答问题，这里没有任何“相对链接”语法。

【解决方案12】：

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

This is [my linked text].

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

这是my linked text。

【讨论】：