GitHub Wiki 页面的添加和设置

目前你们在 GitHub 上发布的项目，通常使用 Markdown 来编写项目文档和 README.md 等。Markdown 通常状况下可以知足咱们的文档编写需求，若是使用得当的话，效果也很是棒。不过当项目文档比较长的时候，阅读体验可能就不是那么理想了，这种状况我想你们应该都曾经遇到过。

GitHub 每个项目都有一个独立完整的 Wiki 页面，咱们能够用它来实现项目信息管理，为项目提供更加完善的文档。咱们能够把 Wiki 做为项目文档的一个重要组成部分，将冗长、具体的文档整理成 Wiki，将精简的、概述性的内容，放到项目中或是 README.md 里。

一. Wiki 简介

Wiki 是一种在网络上开放且可供多人协同创做的超文本系统，由沃德·坎宁安于 1995 年首先开发，这种超文本系统支持面向社群的协做式写做，同时也包括一组支持这种写做。Wiki 站点能够有多人（甚至任何访问者）维护，每一个人均可以发表本身的意见，或者对共同的主题进行扩展或者探讨。

上面这段描述引用自 百度百科，嗯，实际上百度百科自己也是一个 Wiki，最著名的 Wiki 大概是是 维基百科 了吧。

而后 Wiki 页面效果大概能够参考 Kingfisher，看起来仍是很是棒的：

二. Wiki 的开启和关闭

GitHub 项目的 Wikis 功能默认是开启的，若是你没有找到 Wiki 选项卡，多是由于该项目关闭了 Wikis 选项，在项目 Setting 中将其选中便可，如图所示：

若是在以后某一天决定再也不继续使用 Wikis 也能够经过取消该功能的勾选将其关闭，即便已经添加了 Wiki 页面也能够。而且会保存以前的 Wiki 页面内容，即关闭 Wiki 功能并不会清除内容，还能够随时再打开。

三. 建立和编辑页面

GitHub 的 Wiki 页面在如图所示选项卡下，默认应该是开启的，可是是空的，咱们能够点击中间那个绿色的 Create the first page 按钮建立一个页面。

若是你没有找到 Wiki 选项卡，多是由于该项目关闭了 Wikis 选项，在项目 Setting 中将其选中便可，参考上文内容。

点击 Create the first page 按钮后会进入 Create new page 页面：

从上往下进行介绍，顶部的输入框是页面标题；Edit mode 控制编辑页面的标记语言类型，这里默认的是 Markdown，支持的类型以下图所示：

中间的是页面内容，咱们能够用 Edit mode 选择的语法在这里编写页面内容；底部编辑框用来输入本次编辑保存时的提交信息；编辑完成后点击 Save Page 按钮便可保存，唔，保存前能够先切换到 Preview 选项卡下进行预览，看一下效果是不是本身想要的。

而后保存咱们新建的页面，大概会是以下效果：

点击右上角的 Edit 按钮能够对当前页面进行编辑，也能够点击 New Page 按钮继续添加新的页面。

唔，这里有一点须要注意的是，默认的主页标题必须为 Home，若是不存在标题为 Home 的页面，切换到项目的 Wiki 选项卡时，会显示一个全部页面组成的列表。因此咱们的主页必须以 Home 为标题。

目前好像没什么内容，感受比较空额，不过不要紧，接下来咱们会一步步完善。

四. 添加页脚

点击 Wiki 页面底部的 Add a custom footer 按钮，进入新建页脚页面，如图所示：

新建页脚页面实际上就是一个普通的 Create new page 页面，不过标题须要设为 _Footer 而且不能修改（若是修改了就不会被看成页脚来处理了）。

咱们能够参考 Kingfisher 的页脚代码，放置多个超连接在这里供读者在阅读完某一页后快速跳转到关键的章节或页面去，具体代码和效果以下：

[Installation](https://github.com/onevcat/Kingfisher/wiki/Installation-Guide) - [Cheat Sheet](https://github.com/onevcat/Kingfisher/wiki/Cheat-Sheet) - [FAQ](https://github.com/onevcat/Kingfisher/wiki/FAQ) - [API Reference](http://onevcat.github.io/Kingfisher/)
复制代码

固然也能够放一些奇怪的东西，好比，这样的：

如上图所示，点击页脚右侧的编辑按钮，就能够对页脚进行编辑啦，很方便。

五. 添加侧边栏

点击右侧的 Add a custom sidebar 按钮能够添加侧边栏，和页脚同理，页面名为特殊的 _Sidebar：

咱们能够参考 Kingfisher 的侧边栏实现，代码和效果以下：

## Getting Started

* [Getting Started with Kingfisher](https://github.com/onevcat/Kingfisher/wiki/Getting-Started-with-Kingfisher)
 * [Install Kingfisher](https://github.com/onevcat/Kingfisher/wiki/Installation-Guide)
 * [Cheat Sheet](https://github.com/onevcat/Kingfisher/wiki/Cheat-Sheet)
* [API Reference](http://onevcat.github.io/Kingfisher/)

## Migration Guide

* [3.0 Migration Guide](https://github.com/onevcat/Kingfisher/wiki/Kingfisher-3.0-Migration-Guide)
* [2.0 Migration Guide](https://github.com/onevcat/Kingfisher/wiki/Kingfisher-2.0-Migration-Guide)

## Communication

* [FAQ](https://github.com/onevcat/Kingfisher/wiki/FAQ)
* [Ask a question](http://stackoverflow.com/search?q=kingfisher)
* [Submit an issue](https://github.com/onevcat/Kingfisher/issues/new)
* [Open a pull request](https://github.com/onevcat/Kingfisher/compare)

## Information

* [Change Log](https://github.com/onevcat/Kingfisher/blob/master/CHANGELOG.md)
复制代码

这里的话能够本身适当摸索一下，调整标题层级等样式，以得到一个本身比较满意的展现效果。一样的，点击侧边栏右上角的编辑按钮能够对快速侧边栏进行在线编辑。

六. 查看编辑历史

进入某个页面的编辑页面，点击右上角的 Page History 按钮，能够查看该页面的编辑历史，以下图所示：

七. 权限控制

那么问题来了，既然是 Wiki 的话，为啥以上这些内容彻底是项目全部者一我的手撸呢，彻底没有体现出「多人协做」的特性啊喂。

嗯，GitHub Wiki 是能够开放给全部人编辑权限的，不过默认是只有项目全部者和合做者才有权限编辑的，只要到 Setting 中将 Restrict editing to collaborators only 选项去除勾选便可。

这样的话，只要有 GitHub 帐号的用户，均可以对该项目的 Wiki 进行编辑。若是怕被胡乱篡改，不想开放编辑权限的话，仍是保持勾选好了。

八. 本地编辑

唔，上文内容一直在介绍 Wiki 的在线编辑，实际上 Wiki 是一个单独的 Git 仓库，能够 Clone 到本地进行操做

1. Wiki 仓库下载

细心的同窗应该已经注意到了，Wiki 的右下角处有当前 Wiki 的 Git 仓库地址（咱们也能够经过该方法下载他人所属的 Wiki 页面的源代码）：

Kingfisher 的 Wiki 仓库结构以下：

接下来就能够直接对 Wiki 页面源文件进行编辑了，实际上就是一堆 Markdown 文件的组合（或者其余比标记语言，看你选的是啥了）。

2. 本地预览

咱们在本地手动编辑编辑完成后，只能经过 push 到 GitHub 的方式进行预览，很是不方便，这个时候，就须要借助一个叫 gollum 的工具了。

Gollum 是 GitHub 上用到的 Wiki 引擎，使用它能够在本地上搭建一个相似的GitHub Wiki 的网站，对本地的 Wiki 页面进行快速预览。执行如下命令便可安装：

sudo gem install gollum
复制代码

安装完成后，将路径切换到 Wiki 的 Git 仓库下而后执行 gollum 命令，而后访问 http://127.0.0.1:4567/ 便可进行预览。

九. 其余

Wiki 不只仅能够做为项目辅助工具来用，你也能够把它看成一个我的信息知识库来使用，不须要搭建，不须要部署，无需付费，方便快捷，更多功鞥你们能够自行开发。

若是你以为上文的报道，哦不，描述可能有误差，GitHub Wiki 的帮助文档 也许能给你带来一些帮助。

---

再读一篇相似文章？

GitHub 项目徽章的添加和设置

---

若有任何知识产权、版权问题或理论错误，还请指正。 https://juejin.im/post/5a3216c8f265da43333e6b54 转载请注明原做者及以上信息。