相信不少人都有這種經歷,一個項目寫好了,尤爲是一個組件庫,你沒有一個文檔說明,誰能看得懂?因此一個好的項目,必需要有個通俗易懂的文檔說明。固然,這些年markdown如火如荼,github的page也可讓你快速生成一個簡單的文檔說明,但畢竟寫來寫去仍是在一個readme.md上面作文章,若是一個項目或是組件夠大,總不能全部的都寫在一個文件裏面吧!就算你寫的再認真,說實話,也沒人願意去看。javascript
作過前端的小夥伴,element ui想必不陌生,組件庫那是至關不錯,而且對用戶來講很容易入門。爲何?由於他有一個完善的,淺顯易懂的文檔。php
一個偶然的機會了解到docsify,通過一天的摸索以爲有必要寫一點什麼,以防本身從此查閱什麼的。css
npm i docsify-cli -g
複製代碼
初始化必須進到項目根目錄,固然若是你像我同樣只爲了寫一個文檔而寫文檔,新建一個空文件夾就行。可是,在這裏我要稍微弄的複雜一點,由於咱們寫好的文檔總不是寫給本身看,仍是要放到github上面供更多人查閱的。因此咱們就重新建一個空的github庫開始。固然,這過程就不累述了,你們自行建立。建立好以後將repo clone到本地。 html
而後在當前目錄運行以下指令:docsify init ./docs
複製代碼
會在當前目錄新生成一個docs目錄。 前端
裏面包含這三個文件,先無論都有什麼用,我只能告訴你你改的最多的可能就是index.html
以及無限量的添加新的markdown文件了。先無論那麼多,先跑起來看到頁面再說。
docsify serve docs
複製代碼
再次打開瀏覽器:http://localhost:3000就能看到一個初始化的頁面。vue
固然你可能以爲這一長串指令記不住,那我們就來個簡單的。java
打開package.json
,在script裏面添加一條,若是沒有請自行添加:npm init -y
react
"doc": 'docsify serve docs'
複製代碼
之後直接 npm run doc
便可。到了這裏一個簡單的文檔模型就出來了,接下來就着重瞭解一下他的相關配置:ios
太簡單的配置就不累述了,給個地址,你們點進去本身看docsify,接下來重點說一下以下幾個配置項。git
加載自定義導航欄,設置爲true
便可,它會自動加載指定路徑下的_navbar.md
,可是咱們總想什麼東西都要受本身控制,這裏我就簡稱爲碼控
吧!很簡單,咱們在./docs
目錄下新建_navbar.md
,這樣,就能夠在這個文件裏面自定義咱們的側邊欄了。
window.$docsify = {
// 加載 _navbar.md
loadSidebar: true,
// 加載 nav.md
loadSidebar: 'summary.md'
};
複製代碼
新建
setup.md
,如上圖所示:
咱們能夠看到上面所示的樣子,基本上這就是一個文檔的最基礎的樣子。可是功能遠遠沒有達到咱們想要的效果,下面就一塊兒弄幾個插件玩玩!
將下面的js加在index.html
最下面便可。
<script src="//unpkg.com/docsify-copy-code"></script>
複製代碼
而後在
README.md
中隨便寫一點代碼
其餘還有一些插件配置比較簡單,接下來介紹下稍微有些繁瑣的一個。
看名字估計有些小夥伴就知道是幹嗎的,就是一個基於 Github Issue 和 Preact 開發的評論插件。下面一塊兒來了解怎麼使用!
<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
<script> const gitalk = new Gitalk({ clientID: 'Github Application Client ID', clientSecret: 'Github Application Client Secret', repo: 'Github repo', owner: 'Github repo owner', admin: ['Github repo collaborators, only these guys can initialize github issues'], // facebook-like distraction free mode distractionFreeMode: false }) </script>
複製代碼
配置文件就是上面那些,可是上面還有一些東西要咱們本身去填。也就是github application相關的一些配置。 廢話很少說,打開 github.com/settings/de…
添加後咱們就能夠得到相關的配置項:<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Document</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
</head>
<body>
<div id="app"></div>
<script> window.$docsify = { name: '', themeColor: '#19BE6B', repo: '', loadSidebar: true } </script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="//unpkg.com/docsify-copy-code"></script>
<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
<script> const gitalk = new Gitalk({ clientID: '9b4355e11242485017da', clientSecret: 'fe82f322d0571768a6bf838b515105318397e274', repo: 'docsify-starter', owner: 'swimly', admin: ['swimly'], // facebook-like distraction free mode distractionFreeMode: true }) </script>
</body>
</html>
複製代碼
最後index.html
的配置基本上就上面這樣,聲明,我這裏的clientID
,clientSecret
是錯的,切勿直接複製!
最後來一點圖片欣賞一下勞動成果!
到這裏一個基本的文檔就完成了,接下來就是去完善文檔!
因爲前面咱們已經新建了github,直接提交到github的master分支下便可!到這裏還沒完,同步到github,要怎麼讓其餘人能看到纔是關鍵,接下來進行咱們的最後一步,打開最開始咱們新建的github項目,切換到setting
master branch /docs folder
。
上面這裏就是咱們這個文檔的地址,直接點開就能看到最終的效果! 好了,到這裏一個完整的流程就結束了,還有更多玩法等待你們共同發掘!
謝謝瀏覽,歡迎留言,共同討論!