Github wiki 链接规则

Github 为每个代码库提供了一个附带的 wiki。这个 wiki 其实也是个独立的代码库,可以用 git 进行管理,还是挺方便的。不过 Github wiki 在文件结构上有特殊的设计,一开始会觉得有点摸不着头脑。于是就花了点时间做了个实验,得到以下规则:

Github wiki 规则:文件链接

  • 每个 Github wiki 文档至少需要一个标题,否则跳转链接会自动转到 raw.github.com 上去。用若干个 # 来标注一个标题。
  • Github wiki 会把该库里所有的 .md 文件都提到同一个虚拟的 /wiki 目录里。所以无论你目录结构如何复杂,在引用其它 .md 文件时,只需要直接链接到文件名即可。不过这样在使用 Mou 写作预览时可能反而不方便了,所以最简单的办法是把所有 .md 文件都放在根目录里。
  • 仅 .md 如此特殊处理(也许还有其它 Markup 文件),对于图片等其它附件,均保持自己相对路径。
  • 尽管如此,home.md 却属特例。它在虚拟的 /wiki 目录的上一层。所以由它引用到别的文件,均需要加上 /wiki

Github wiki 规则:锚点

  • 任意用 1-6 个 # 标注的标题会自动被添加上同名锚点。在链接中写入锚点即可跳转,比如: [显示文本](wiki/sample#anchor) 对应 sample.md 内的某个标题: ### Anchor
  • 锚点中英文皆可,使用中文(或其它文字)会自动 Encode 和 Decode。但只有英文(可能有其它语言)可以大小写通用。
  • 由于 .md 本身写链接的限制,多单词锚点的空格用-代替。比如#regist-github对应###Regist GitHub
  • 即使页内锚点,也必须写上文件名,如果不写,锚点链接会自动添加 “wiki-” 前缀,比如: [显示文本](#anchor) 对应的是 #wiki-anchor。
  • 如上,如果对应的标题名真的就是 wiki-Anchor,那么锚点也还是能正常工作的。

Github wiki 官方说明:https://github.com/features/projects/wikis