docsify - 生成文檔網站簡單使用教程

時間  2019-11-06
標籤 docsify 生成 文檔 網站 簡單 使用 教程 欄目 網站開發 简体版
原文   原文鏈接

1. docsify介紹

docsify 是一個動態生成文檔網站的工具。不一樣於 GitBook、Hexo 的地方是它不會生成將 .md 轉成 .html 文件，全部轉換工做都是在運行時進行。javascript

這將很是實用，若是隻是須要快速的搭建一個小型的文檔網站，或者不想由於生成的一堆 .html 文件「污染」 commit 記錄，只須要建立一個 index.html 就能夠開始寫文檔並且直接部署在 GitHub Pages。css

2. 引入docsify方式

2.1 手動建立index.html並引入docsify文件

docsify使用方式很簡單，只須要在項目中建立一個index.html文件，內容可以以下：html

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>

而後在項目中建立一個README.md文件：vue

## 我是首頁

這是個人首頁介紹

若是你的系統安裝了Python 的話，可使用Python來啓動一個服務：java

python -m SimpleHTTPServer 3000

Serving HTTP on 0.0.0.0 port 3000 ...
127.0.0.1 - - [03/Jan/2019 13:45:27] "GET / HTTP/1.1" 200 -

clipboard.png
而後在瀏覽器中輸入http://localhost:3000/查看瀏覽效果。node

若是沒有Python，仍是可使用http-server啓動服務，
可在終端輸入npm install http-server -g來安裝http-server。python

http-server 

Starting up http-server, serving ./
Available on:
  http://127.0.0.1:8080
  http://172.24.70.142:8080
Hit CTRL-C to stop the server

clipboard.png
而後在瀏覽器中輸入http://127.0.0.1:8080查看瀏覽效果。react

clipboard.png

注意：
1.在此模式下編輯文件保存後，須要手動刷新瀏覽器才能看見修改的效果，下面介紹的docsify-cli可實現自動查看效果。
2.強烈建議把index.html文件中的docsify.min.js和vue.css文件複製到本地項目，而後使用以下方式引入：git

<link rel="stylesheet" href="./vue.css">
<script src="./docsify.min.js"></script>

這樣作的好處是不在依賴網絡環境了。github

2.2 使用docsify-cli來開發

docsify-cli 工具，能夠方便建立及本地預覽文檔網站。

2.2.1 安裝

docsify須要本地先安裝node, 若是沒有安裝node，可在node官網選擇對應操做系統下載安裝：https://nodejs.org/zh-cn/

終端輸入npm i docsify-cli -g進行全局安裝：

npm i docsify-cli -g

/usr/local/bin/docsify -> /usr/local/lib/node_modules/docsify-cli/bin/docsify
> fsevents@1.2.4 install /usr/local/lib/node_modules/docsify-cli/node_modules/fsevents
> node install
[fsevents] Success: "/usr/local/lib/node_modules/docsify-cli/node_modules/fsevents/lib/binding/Release/node-v57-darwin-x64/fse.node" already installed
Pass --update-binary to reinstall or --build-from-source to recompile
> docsify@4.8.6 postinstall /usr/local/lib/node_modules/docsify-cli/node_modules/docsify
> opencollective postinstall

                         Thanks for installing docsify 🙏
                 Please consider donating to our open collective
                        to help us maintain this package.

          👉  Donate: https://opencollective.com/docsify/donate

+ docsify-cli@4.3.0
added 456 packages from 206 contributors in 32.827s

clipboard.png

安裝結束後使用docsify -v查看是否安裝成功：

docsify -v

docsify-cli version:
  4.3.0

2.2.2 初始化一個項目

首先須要建立一個項目目錄：

mkdir docsify

進入項目目錄後，使用docsify init ./來初始化一個項目：

cd docsify

docsify init ./

Initialization succeeded! Please run docsify serve ./
tree -a

.
├── .nojekyll
├── README.md
└── index.html

初始化成功後,docsify目錄會生成以下幾個文件：

  1. index.html入口文件
  2. README.md會作爲主頁內容渲染
  3. .nojekyll用於阻止 GitHub Pages 會忽略掉下劃線開頭的文件、

.nojekyll文件很重要，若是網站部署到GitHub Pages時，必定要注意這個文件。

直接編輯 ./README.md 就能更新網站內容，固然也能夠添加其餘.md文件。

2.2.3 啓動本地服務

終端輸入docsify serve ./來啓動服務：

docsify serve ./

Serving /Users/dragon/tmp/docsify now.
Listening at http://localhost:3000

而後瀏覽器打開http://localhost:3000就能看見效果。

clipboard.png

當修改文件保存後， docsify serve ./服務會自動實時更新。

3. 關於每一個頁面和URL路徑說明

若是須要建立多個頁面，或者須要多級路由的網站，在docsify裏也能很容易的實現。例如建立一個guide.md文件，那麼對應的路由就是/#/guide。
若是你的目錄結構以下：

-| ./
  -| README.md
  -| guide.md
  -| zh-cn/
    -| README.md
    -| guide.md

那麼對應的訪問頁面將是:

./README.md        => http://domain.com
./guide.md         => http://domain.com/guide
./zh-cn/README.md  => http://domain.com/zh-cn/
./zh-cn/guide.md   => http://domain.com/zh-cn/guide

4. 側邊欄設置

默認狀況下，側邊欄會根據當前文檔的標題生成目錄。

clipboard.png

4.1 定製側邊欄

首先須要在index.html文件中的window.$docsify添加loadSidebar: true,選項：

<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="//unpkg.com/docsify"></script>

接着在項目根目錄建立_sidebar.md文件，內容格式以下：

* [home1](home1)
* [home2](home2)
* [bar](bar/)
* [bar/a](bar/a)

clipboard.png

注：配置了loadSidebar後就不會生成默認的側邊欄了。

4.2 關於側邊欄_sidebar.md文件的說明

  • 若是隻在根目錄有一個_sidebar.md文件，那麼全部頁面都將使用這個一個配置，也就是全部頁面的側邊欄都同樣。
  • 若是一個子目錄中有_sidebar.md文件，那麼這個子目錄下的全部頁面將使用這個文件的側邊欄。
  • _sidebar.md的加載邏輯是從每層目錄下獲取文件，若是當前目錄不存在該文件則回退到上一級目錄。例如當前路徑爲/zh-cn/more-pages則從/zh-cn/_sidebar.md獲取文件，若是不存在則從/_sidebar.md獲取。

若是子目錄有_sidebar.md,但你就想使用根目錄的_sidebar.md，
可在index.html文件中的window.$docsify添加alias字段：

<script>
  window.$docsify = {
    loadSidebar: true,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md'
    }
  }
</script>

配置alias字段後，全部頁面都會顯示項目根目錄_sidebar.md文件的配置做爲側邊欄，子目錄的_sidebar.md文件會失效。

4.3 顯示頁面目錄(當前頁面的標題)

定製的側邊欄僅顯示了頁面的連接。
還能夠設置在側邊欄顯示當前頁面的目錄(標題)。
須要在index.html文件中的window.$docsify添加subMaxLevel字段來設置：

<script>
  window.$docsify = {
    loadSidebar: true,
    subMaxLevel: 3
  }
</script>
<script src="//unpkg.com/docsify"></script>

clipboard.png

subMaxLevel說明：

subMaxLevel類型是number(數字)，表示顯示的目錄層級
注意：若是md文件中的第一個標題是一級標題，那麼不會顯示在側邊欄，如上圖所示
值 說明
0 默認值，表示不顯示目錄
1 顯示一級標題(h1)
2 顯示1、二級標題(h1 ~ h2)
3 顯示1、2、三級標題(h1 ~ h3)
n n是數字，顯示1、2、....n 級標題(h1 ~ hn)

在md文件中標題的寫法：

# 這是一級標題，對應HTML中<h1>標籤

## 這是二級標題，對應HTML中<h2>標籤

### 這是三級標題，對應HTML中<h3>標籤

#### 這是四級標題，對應HTML中<h4>標籤

4.3.1 頁面的標題不在側邊欄目錄顯示

注意： 若是md文件的第一個標題是一級標題，那麼默認已經忽略了。

當設置了 subMaxLevel 時，默認狀況下每一個標題都會自動添加到目錄中。若是你想忽略特定的標題，能夠給它添加 {docsify-ignore} ：

# Getting Started

## Header {docsify-ignore}

該標題不會出如今側邊欄的目錄中。

要忽略特定頁面上的全部標題，你能夠在頁面的第一個標題上使用 {docsify-ignore-all} :

# Getting Started {docsify-ignore-all}

## Header

該頁面全部標題都不會出如今側邊欄的目錄中。

在使用時， {docsify-ignore} 和 {docsify-ignore-all} 都不會在頁面上顯示。

5. 導航欄配置

docsify默認是沒有導航欄的，能夠經過配置來顯示導航欄。

5.1 在index.html中定義導航欄

若是導航的連接少，則能夠直接在index.html文件直接定義導航欄，要注意連接要以#/開頭：

<body>
  <nav>
    <a href="#/">項目</a>
    <a href="#/home1">home1</a>
    <a href="#/bar/a">bar/a</a>
  </nav>
</body>

clipboard.png

5.2 經過配置文件定義導航欄

首先須要在index.html文件中的window.$docsify添加loadNavbar: true,選項：

<script>
  window.$docsify = {
    loadNavbar: true
  }
</script>
<script src="//unpkg.com/docsify"></script>

接着在項目根目錄建立_navbar.md文件，內容格式以下：

* [home1](home1)
* [home2](home2)
* [bar](bar/)
* [bar/a](bar/a)

clipboard.png

注意：
1.若是使用配置文件來設置導航欄，那麼在 index.html中定義的導航欄只有在定製的首頁纔會生效，其餘頁面會被覆蓋。
2.若是隻在根目錄有一個 _navbar.md文件，那麼全部頁面都將使用這個一個配置，也就是全部頁面的導航欄都同樣。
3.若是一個子目錄中有 _navbar.md文件，那麼這個子目錄下的全部頁面將使用這個文件的導航欄。
4. _navbar.md的加載邏輯是從每層目錄下獲取文件，若是當前目錄不存在該文件則回退到上一級目錄。例如當前路徑爲 /zh-cn/more-pages則從 /zh-cn/_navbar.md獲取文件，若是不存在則從 /_navbar.md獲取。

5.3 導航欄嵌套

若是導航內容過多，能夠寫成嵌套的列表，會被渲染成下拉列表的形式：

* 根目錄
  * [home1](home1)
  * [home2](home2)
  * [guide](guide)

* bar目錄
  * [bar](bar/)
  * [a文件](bar/a)
  * [b文件](bar/b)

* foo目錄
  * [one](foo/one)

clipboard.png

6. 設置封面

docsify默認是沒有封面的，默認有個首頁./README.md。
經過設置coverpage參數，能夠開啓渲染封面的功能。

首先須要在index.html文件中的window.$docsify添加coverpage: true選項：

<script>
  window.$docsify = {
    coverpage: true
  }
</script>
<script src="//unpkg.com/docsify"></script>

接着在項目根目錄建立_coverpage.md文件，內容格式以下：

![logo](_media/icon.svg)
# 個人文檔網站
## 我的文檔網站
> 一個神奇的文檔網站生成鞏固

* Simple and lightweight (~12kb gzipped)
* Multiple themes
* Not build static html files

[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#quick-start)
[Get Started](#quick-start)

clipboard.png

注：一份文檔只會在根目錄下加載封面，其餘頁面或者二級目錄下都不會加載。

6.1 自定義封面背景

目前的背景是隨機生成的漸變色，每次刷新都會顯示不一樣的顏色。
docsify封面支持自定義背景色或者背景圖，在_coverpage.md文檔末尾添加：

<!-- 背景圖片 -->
![](_media/bg.png)

<!-- 背景色 -->
![color](#2f4253)

clipboard.png

注意：
1.自定義背景配置必定要在 _coverpage.md文檔末尾。
2.背景圖片和背景色只能有一個生效.
3.背景色必定要是 #2f4253這種格式的。

6.2 把封面做爲首頁

配置了封面後，封面和首頁是同時出現的，封面在上面，首頁在下面。
經過設置onlyCover參數，可讓docsify網站首頁只顯示封面，
原來的首頁經過http://localhost:3000/#/README訪問。

在index.html文件中的window.$docsify添加onlyCover: true,選項：

<script>
  window.$docsify = {
    coverpage: true,
    onlyCover: true,
  }
</script>
<script src="./docsify.min.js"></script>
經過此配置能夠把 ./README.md文件獨立出來，當成項目真正的README介紹文件。

6.3 多個封面

若是你的文檔網站是多語言的，或許你須要設置多個封面。
例如你的文檔目錄結構以下

.
└── docs
    ├── README.md
    ├── guide.md
    ├── _coverpage.md
    └── zh-cn
        ├── README.md
        └── guide.md
        └── _coverpage.md

那麼你能夠在index.html文件中的window.$docsify這麼配置:

window.$docsify = {
  coverpage: ['/', '/zh-cn/']
};

或者具體指名文件名:

window.$docsify = {
  coverpage: {
    '/': 'cover.md',
    '/zh-cn/': 'cover.md'
  }
};

7. 網站部署到GitHub Pages

GitHub Pages 支持從三個地方讀取文件:

一、 master分支
二、 master分支下的 docs目錄
三、 gh-pages分支
一、若是你的文檔直接是在項目根目錄寫的，那麼可直接把代碼推送到master分支上， GitHub Pages裏選擇 master branch.
2.若是你的文檔是在master分支下的 docs/目錄下編寫的，那麼可直接把代碼推送到master分支上， GitHub Pages裏選擇 master branch/docs folder.

本例子項目是直接在根目錄中編寫的，因此GitHub Pages裏選擇master branch的方式部署。

首先在github網站上建立好倉庫，而後終端打開項目目錄：

git init
git add .
git commit -m 'docsify項目初始化'
git remote add origin https://github.com/username/docsify.git
git push --set-upstream origin master

代碼推送到github上後，打開github的倉庫，選擇Settings -> GitHub Pages -> master branch -> save。

clipboard.png

clipboard.png

7.1 使用docsify的例子

https://spiritree.github.io/n...

https://ripperhe.com/awesome-...

8. 一些插件

8.1 搜索插件

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

<script>
    window.$docsify = {
      // 完整配置參數
      search: {
        maxAge: 86400000,               // 過時時間，單位毫秒，默認一天
        paths: [],                      // or 'auto'，匹配文件路徑
        placeholder: 'Type to search',  // 搜索提示框文字， 支持本地化，例子在下面
        // placeholder: {
        //   '/zh-cn/': '搜索',
        //   '/': 'Type to search'
        // },
        noData: 'No Results!',          // 找不到結果文字提示，支持本地化，例子在下面
        // noData: {
        //   '/zh-cn/': '找不到結果',
        //   '/': 'No Results'
        // },
        depth: 2,                       // 搜索標題的最大程級, 1 - 6
      }
    }
  </script>
  <!-- 引入搜索模塊 -->
  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

8.2 評論插件Gitalk

Gitalk：一個現代化的，基於Preact和Github Issue的評論系統。
使用例子：

<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>

Gitalk具體使用教程：https://segmentfault.com/a/11...

docsify其餘插件：https://docsify.js.org/#/zh-c...

8.3 樣式插件

在網上找到一個樣式：https://jhildenbiddle.github....

使用方法,在HTML文件中引入：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">

參考資料

docsify中文官網：https://docsify.js.org/#/zh-cn/

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程