GitHub Wiki 頁面的新增和設定

EyreFree發表於2017-12-27

目前大家在 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)
複製程式碼