入坑 docsify，一款神奇的文檔生成利器！

時間 2020-11-21

標籤 javascript css html java node linux nginx git github npm 欄目 JavaScript 简体版

原文原文鏈接

layout: post
category: java
title: 入坑 docsify，一款神奇的文檔生成利器！
tagline: by 沉默王二
tags: javascript

- java

Guide 哥是我認識的一個很是優秀的年輕人，胖嘟嘟的身軀裏充斥着無窮無盡的才華，他的 JavaGuide 在 GitHub 上已經標星 91K+ 了，空閒的時候我都會上去瞅兩眼，畢竟學習使我快樂，嘿嘿。css

有一天，我發現，他整的那個在線版看起來很是漂亮，我就問他用什麼作的，他就會回我說，「docsify，很方便。」恰好我最近在更新《教妹學 Java》專欄，就也想整個在線版的，方便讀者閱讀。html

0一、docsify 是什麼

一款神奇的文檔生成利器java

自從有了 Markdown，我就再沒用過富文本編輯器，由於 Markdown 的書寫有一種心流的感受。不少博客平臺都支持 Markdown 了，即使是不支持，也不要緊，能夠經過 mdnice 或者 Md2All 轉成富文本的格式。node

docsify 能夠自動地將 Markdown 中的標題生成目錄，而且能夠配合碼雲（國內的訪問速度比 GitHub Pages 更快）快速搭建一個小型的文檔網站，整個頁面的配色和佈局也十分溫馨，讓閱讀體驗在不知不覺中提高了好幾個檔次。linux

和 Gitbook 不一樣，docsify 不會生成靜態的 HTML 文件，它會智能地加載和解析 Markdown 文件，這就避免了 HTML 文件對整個文檔庫的「污染」。nginx

貼一下 docsify 的官網：git

https://docsify.js.org/github

點進去後你會感受很是的賞心悅目，滿滿的小清新。不得不認可，個人眼睛被它深深地吸引了。npm

0二、入坑 docsify

第一步，打開命令行，執行如下命令安裝 docsify-cli，方便本地初始化和實時預覽。

npm i docsify-cli -g

若是這一步很是很是慢的話，能夠強制退出，由於 npm 是從國外服務器下載的，受網絡影響較大。

淘寶團隊幫咱們解決了這個煩惱，搞了一個 npm 的國內鏡像。能夠經過執行下面的命令把 npm 替換成 cnpm。

npm install -g cnpm --registry=https://registry.npm.taobao.org

若是出現 Error: EACCES: permission denied, access '/usr/local/lib/node_modules' 錯誤的話，是由於執行命令時沒有得到管理員權限，解決方案就在 npm 前面加上 sudo：

sudo npm install -g cnpm --registry=https://registry.npm.taobao.org

輸入密碼後就能夠執行成功了。而後執行 cnpm i docsify-cli -g 命令進行安裝。若是還提示權限錯誤（Error: EACCES: permission denied）的話，記得加上 sudo。

PS：sudo 是一個 linux 系統管理指令，容許系統管理員讓普通用戶執行一些 root 級別的命令。

安裝成功後，會提示如下信息。

第二步，執行如下命令建立文檔目錄並初始化。

docsify init ./docs

進入 docs 目錄後，能夠看到 README.md（作爲主頁內容渲染）和 index.html（入口文件）兩個文件。

第三步，回到 docs 的上級目錄，執行如下命令啓動本地服務。

docsify serve docs

第四步，在瀏覽器地址欄輸入 http://localhost:3000 進行預覽。

0三、自定義導航欄

打開 index.html 文件，在 body 標籤中添加 nav 標籤，以下所示：

<body>
  <nav>
      <a href="www.itwanger.com">沉默王二我的博客</a>
  </nav>
  <div id="app"></div>
</body>

保存後，就能夠在瀏覽器上查看到效果。

0四、定製化配置項

打開 index.html 文件，在 script 標籤中對 window.$docsify 進行配置，以下所示：

window.$docsify = {
        name: '教妹學Java',
        repo: 'https://github.com/itwanger/TechSisterLearnJava',
}

1）name：文檔標題，會顯示在側邊欄頂部。

2）repo：GitHub 上的倉庫地址，會在頁面右上角渲染一個 GitHub 角標。

保存後，就能夠在瀏覽器上查看到效果。

0五、安裝插件

1）全文搜索

全文搜索插件會根據當前頁面上的超連接獲取文檔內容，在 localStorage 內創建文檔索引。默認過時時間爲一天，也能夠指定須要緩存的文件列表或者過時時間。

打開 index.html 文件，添加全文搜索配置項，並引入 search.min.js，以下所示：

<body>
  <script>
    window.$docsify = {
      search: {
        paths: 'auto',
        placeholder: '搜索',
        noData: '找不到結果',
        depth: 3,
      },
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>

保存後，就能夠在瀏覽器上查看到效果。

2）圖片縮放

在 index.html 文件中引入 zoom-image.min.js 便可，以下所示：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>

保存後，就能夠在瀏覽器上查看到效果，鼠標放到一張圖片上時會出現縮小或者放大的圖標，點擊後就能夠改變圖片的形態。

3）複製到剪貼板

在全部的代碼塊上添加一個簡單的 Click to copy 按鈕來容許用戶從你的文檔中輕易地複製代碼。在 index.html 文件中引入 docsify-copy-code 便可，以下所示：

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>

保存後，就能夠在瀏覽器上查看到效果。

4）字數統計

提供了統計中文漢字和英文單詞的功能，而且排除了一些 markdown 語法的特殊字符例如 *、- 等。

打開 index.html 文件，添加 count 配置項，並引入 countable.js，以下所示：

<body>
  <script>
    window.$docsify = {
      count:{
        countable:true,
        fontsize:'0.9em',
        color:'rgb(90,90,90)',
        language:'chinese'
      }
    }
  </script>
<script src="//unpkg.com/docsify-count/dist/countable.js"></script>
</body>

保存後，就能夠在瀏覽器上查看到效果。

0六、代碼高亮

docsify 內置的代碼高亮工具是 Prism。Prism 默認支持的語言以下：

Markup - markup, html, xml, svg, mathml, ssml, atom, rss
CSS - css
C-like - clike
JavaScript - javascript, js

Java 須要在 index.html 文件中添加額外的語法文件，以下所示：

<script src="https://cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-java.min.js"></script>

保存後，就能夠在瀏覽器上查看到效果。

0七、部署到碼雲

咱們能夠把文檔網站部署到 GitHub Pages 上，但對於國內用戶來講，碼雲的訪問速度顯然會更快一些。

若是你是第一次使用 GitHub 的話，我這裏已經爲你準備好了教程：

文科妹子都會用 GitHub，你這個工科生還等什麼

在 GitHub 上新建一個倉庫，把你的文檔所有放到 docs 目錄下，個人已經建立好了，就叫 TechSisterLearnJava。

接下來，登陸碼雲，選擇從 GitHub 導入倉庫。

選擇對應倉庫後點擊導入。

導入成功後，點擊「查看倉庫」，就能夠看到從 GitHub 導入到碼雲的倉庫。點擊「服務」，選擇「Gitee Pages」。

勾選強制啓用 HTTPS，而後點擊「啓動」按鈕。不一下子，碼雲 Pages 服務就開啓了。

點擊網站地址：

https://itwanger.gitee.io/zero-learn-java

就能夠看到 docsify 已經成功部署到碼雲上了。

0八、最後

強烈推薦一下《教妹學 Java》專欄，目前已更新 15 節內容（近 5 萬字），後面每週至少會更新 2 節，預計更新 130 節，從 Java 的基礎知識到對象和類，再到集合框架、網絡編程、併發編程和 Java 虛擬機，基本上全方位覆蓋。

專欄中涉及到的圖片都花了我不少精力和心思，力爭給你一種耳目一新的感受，隨便截幾張圖給你看看。

這麼好的專欄上哪去找呢？免費給你（反正我也不知道本身是怎麼想的）！

GitHub 閱讀地址（star 它）：

https://github.com/itwanger/zero-learn-java

碼雲閱讀地址（star 它）：

https://gitee.com/itwanger/zero-learn-java

docsify 在線閱讀地址：

https://itwanger.gitee.io/zero-learn-java

我知道，我知道，不用你開口，離線版的 PDF 我也準備好了，看這暗黑風格的 PDF，閱讀起來絕壁賞心悅目啊。

百度網盤下載（暗黑和亮白，兩種）地址：

https://pan.baidu.com/s/1qwomiFHW6vZdVo26heMctg 密碼:1thn

PS：整完這個 docsify 後，我累壞了，一瞅時間，凌晨 1 點 32 分了，說實話，眼睛已經迷離了。

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。