docsify， 一款神奇的文檔生成工具

最近，在整理項目時，總感覺文檔不夠全面，希望有一款能夠簡單配置就能書寫文檔的工具，通過對gitbook、docusaurus、docsify的研究發現，制作一份精致的文檔，

那么使用docsify是不錯的選擇，docsify是一個文檔生成工具，它直接加載 Markdown 文件並動態渲染，同時還可以生成封面頁。所以我們只需要寫完 Markdown 文檔，就可以看到文檔頁面了。

docsify介紹

docsify 可以快速幫你生成文檔網站。docsify 可以自動地將 Markdown 中的標題生成目錄，並且可以配合碼雲（國內的訪問速度比 GitHub Pages 更快）快速搭建一個小型的文檔網站，整個頁面的配色和布局也十分舒適，讓閱讀體驗在不知不覺中提升了好幾個檔次。

不同於 GitBook、Hexo 的地方是它不會生成靜態的 .html 文件，所有轉換工作都是在運行時。如果你想要開始使用它，只需要創建一個 index.html 就可以開始編寫文檔並直接部署在 GitHub Pages。

 

特性

• 無需構建，寫完文檔直接發布
• 容易使用並且輕量 (~19kB gzipped)
• 智能的全文搜索
• 提供多套主題
• 豐富的 API
• 支持 Emoji
• 兼容 IE10+
• 支持 SSR (example)

 

一、快速搭建

docsify與Vue cli很相似，都依賴於Node.js，首先需要安裝Node.js支持環境，開發才能正常進行。

1.全局安裝docsify

#使用npm安裝docsfiy-cli 腳手架

npm i docsify-cli -g 

安裝完成之后就可以看到如下圖所示

2.查看版本

docsify -v  #查看版本

3. 初始化項目

使用命令 docsify init ./項目名初始化項目

docsify init ./項目名  #初始化項目

初始化一個名為mydocs的項目，mydocs是自己命名的項目名

 

 初始化成功后，可以看到已經生成了一個名為mydocs的項目，里面包含3個文件index.html、README.md、.nojekyll。

 

• index.html 入口文件
• README.md 會做為主頁內容渲染
• .nojekyll 用於阻止 GitHub Pages 會忽略掉下划線開頭的文件

 

4.運行項目

在項目文件同一級目錄，使用命令docsify serve 項目名啟動項目

#不指定端口，默認端口是3000
docsify serve 項目名 
#指定端口
docsify serve 項目名 --port 端口

 

 

5.訪問項目 

在瀏覽器輸入項目地址http://localhost:4000/，出現如下界面，代表已經搭建成功了!!!

 

 

二、常用配置項

下面做一些常用項的介紹，如需了解更多配置，可以參考官方文檔。

1. 標題與 GitHub Corner 掛件

通過設置index.html中window.$docsify的 repo 參數配置倉庫地址或者 username/repo 的字符串，會在頁面右上角渲染一個 GitHub Corner 掛件，點擊即可跳轉到Github中對應的項目地址。

<script>
    window.$docsify = {
      name: '我的文檔',
      repo: 'https://github.com/Hanxueqing/Douban-Movie.git'
    }
</script>

 

 

 

 

 2.封面

通過設置index.html中window.$docsify的 coverpage 參數，即可開啟渲染封面的功能。

<script>
    window.$docsify = {
    　　name: '文檔中心',//標題名稱
    　　repo: '',//GitHub Corner 掛件
    　　coverpage: true,//激活封面功能。如果為true，則會從中加載_coverpage.md。
    }
</script>

封面的生成同樣是從 markdown 文件渲染來的。開啟渲染封面功能后在文檔根目錄創建 _coverpage.md 文件，在文檔中編寫需要展示在封面的內容。

![logo](httpsdocsify.js.org_mediaicon.svg)

# 我的文檔

 使用docsify搭建在線文檔.


[GitHub](httpsgithub.comHanxueqingDouban-Movie.git)
[Get Started](#quick-start)

 展示效果如圖：

 

 

目前的背景是隨機生成的漸變色，我們自定義背景色或者背景圖。可以參考官網文檔封面這一章節自行設置。 

3.主題

直接打開 index.html 修改替換 css 地址即可切換主題，官方目前提供五套主題可供選擇，模仿 Vue 和 buble 官網訂制的主題樣式。還有 @liril-net 貢獻的黑色風格的主題。

<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dark.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/pure.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dolphin.css">

其他主題docsify-themeable又提供了三種樣式（Defaults、Simple、Simple Dark）可供選擇，需要使用的時候使用其中一種就可以了：

<!-- Theme: Defaults -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
<!-- Theme: Defaults -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
<!-- Theme: Simple Dark -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">

其他樣式風格

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

 

4.多頁面

README.md作為主頁面，如果需要創建多個頁面，或者需要多級路由的網站，在 docsify 里也能很容易的實現。直接在文檔目錄下創建對應的 *.md 文件，例如創建一個guide.md那么對應的路由就是/#/guide。

假設你的目錄結構如下：

.
└── mydocs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md

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

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

 

4.定制側邊欄

為了獲得側邊欄，您需要創建自己的_sidebar.md，你也可以自定義加載的文件名。默認情況下側邊欄會通過 Markdown 文件自動生成，效果如當前的文檔的側邊欄。

首先配置 loadSidebar 選項，在index.html里面，修改配置，具體配置規則見配置項#loadSidebar。

<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

創建一個_sidebar.md文件，內容如下

* [首頁](zh-cn/)
* [指南](zh-cn/guide)

注意：需要在 ./mydocs 目錄創建 .nojekyll 命名的空文件，阻止 GitHub Pages 忽略命名是下划線開頭的文件。

5.頂部導航欄

 方法一：如果項實現頂部navbar導航欄，可以開啟頂部導航配置，loadNavbar: true

<script>
    window.$docsify = {
      name: '文檔中心',
      repo: '',
      loadSidebar: true, //側邊欄
      loadNavbar: true,//頂部導航
    }
</script>

然后新建一個_navbar.md，文件內容如下：

* [EN](/)
* [中文](/zh-cn/)

方法二：也可以不使用上述方式，而是直接修改index.html文件，

<body>
        <!-- 頂部導航 -->
        <nav>
            <a href="#/">EN</a>
            <a href="#/zh-cn/">中文</a>
        </nav>
        <div id="app"></div>
        <script>
            window.$docsify = {
                name: '文檔中心',
                repo: '',
                loadSidebar: true, //側邊欄
            }
        </script>
        <!-- Docsify v4 -->
        <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
</body>

實現效果

 

三、安裝插件

1.引入emoji插件

如果在做中英文切換時，想使用中國國旗和英國國旗表示，怎么辦呢？docsify為我們提供了表情插件，使用docsify的emoji插件來獲取國家的國旗。

只需要在index.html配置文件中引入emoji插件就可以直接在markdown文件中直接使用了！

引入了：<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>

 

<script>
     window.$docsify = {
          name: '文檔中心',
          repo: '',
          loadSidebar: true, //側邊欄
          loadNavbar: true, //頂部導航
     }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>

 

配置_navbar.md文件，修改內容如下

* [:us:, :uk:](/)
* [:cn:](/zh-cn/)

顯示效果

 

 

1.PDF導出

https://blog.csdn.net/weixin_43031092/article/details/114419659

 

1.全文搜索

 https://baijiahao.baidu.com/s?id=1683928475208184783&wfr=spider&for=pc

 

搭建配置

https://www.e-learn.cn/topic/3930849

 

 

我們直接創建一個index.html文件。

有了docsify神器，從此愛上看文檔

1.https://www.jianshu.com/p/4883e95aa903

2.https://baijiahao.baidu.com/s?id=1683928475208184783&wfr=spider&for=pc

3.https://juemuren4449.com/archives/docsify-deploy-and-configuration

4.https://www.e-learn.cn/topic/3930849

5.https://docsify.js.org/#/zh-cn/

6.https://www.e-learn.cn/topic/3930849