docsify,文檔生成利器!

前沿

相信不少人都有這種經歷,一個項目寫好了,尤爲是一個組件庫,你沒有一個文檔說明,誰能看得懂?因此一個好的項目,必需要有個通俗易懂的文檔說明。固然,這些年markdown如火如荼,github的page也可讓你快速生成一個簡單的文檔說明,但畢竟寫來寫去仍是在一個readme.md上面作文章,若是一個項目或是組件夠大,總不能全部的都寫在一個文件裏面吧!就算你寫的再認真,說實話,也沒人願意去看。javascript

原由

作過前端的小夥伴,element ui想必不陌生,組件庫那是至關不錯,而且對用戶來講很容易入門。爲何?由於他有一個完善的,淺顯易懂的文檔。php

起步

一個偶然的機會了解到docsify,通過一天的摸索以爲有必要寫一點什麼,以防本身從此查閱什麼的。css

安裝docsify
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 -yreact

"doc": 'docsify serve docs'
複製代碼

之後直接 npm run doc便可。到了這裏一個簡單的文檔模型就出來了,接下來就着重瞭解一下他的相關配置:ios

配置

太簡單的配置就不累述了,給個地址,你們點進去本身看docsify,接下來重點說一下以下幾個配置項。git

loadSidebar

加載自定義導航欄,設置爲true便可,它會自動加載指定路徑下的_navbar.md,可是咱們總想什麼東西都要受本身控制,這裏我就簡稱爲碼控吧!很簡單,咱們在./docs目錄下新建_navbar.md,這樣,就能夠在這個文件裏面自定義咱們的側邊欄了。

window.$docsify = {
  // 加載 _navbar.md
  loadSidebar: true,

  // 加載 nav.md
  loadSidebar: 'summary.md'
};
複製代碼

新建 setup.md,如上圖所示:
咱們能夠看到上面所示的樣子,基本上這就是一個文檔的最基礎的樣子。可是功能遠遠沒有達到咱們想要的效果,下面就一塊兒弄幾個插件玩玩!

插件

copy to clipboard

將下面的js加在index.html最下面便可。

<script src="//unpkg.com/docsify-copy-code"></script>
複製代碼

而後在 README.md中隨便寫一點代碼

其餘還有一些插件配置比較簡單,接下來介紹下稍微有些繁瑣的一個。

Gittalk

看名字估計有些小夥伴就知道是幹嗎的,就是一個基於 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,直接提交到github的master分支下便可!到這裏還沒完,同步到github,要怎麼讓其餘人能看到纔是關鍵,接下來進行咱們的最後一步,打開最開始咱們新建的github項目,切換到setting

找到GitHub pages,將source改爲 master branch /docs folder
上面這裏就是咱們這個文檔的地址,直接點開就能看到最終的效果! 好了,到這裏一個完整的流程就結束了,還有更多玩法等待你們共同發掘!

一些連接

doc地址 github

謝謝瀏覽,歡迎留言,共同討論!

相關文章
相關標籤/搜索