Docsify个人网站搭建详细教程
目錄
- 一、什么是 docsify
- 二、安裝 docsify
- 三、多頁文檔設置
- 四、定制化配置
- 4.1、側邊欄
- 4.2、導航欄
- 4.3、封面
- 4.4、主題
- 五、部署
- 5.1、部署到Gitee
- 5.2、部署到云服務器
一、什么是 docsify
docsify是一個有魔法的文檔網站生成器，它能夠動態生成您的文檔網站。與GitBook、Hexo不同，它不生成靜態html文件，而是智能地加載和解析您的md文件，并將其顯示為網站。要開始使用它，只需創建一個
index.html并將其部署在GitHub Page/Gitee Page等第三方站點上即可。官網：docsify
特點：
- 無需構建靜態的html文件
- 輕量
- 擁有智能的全文搜索插件
- 支持多主題
- 支持豐富的API插件
- 支持表情符號
- 兼容 IE11
- 支持服務端的渲染
以前曾經折騰過一段時間 hexo 個人靜態博客，總體來說還是比較滿意的，hexo 也支持md渲染、一鍵部署、包括很多三方的插件和豐富的拓展性，唯一的不足可能就是相比 docify 配置比較麻煩，兩者最大的區別就是當本地文件變更的時，hexo 需要首先通過hexo -c清空目前生成的靜態網頁文件，然后再通過hexo -g根據本地變更后的新文件構建出一個 public目錄存放網站的靜態文件，然后如果需要查看效果的話，還需通過hexo -s啟動本地的hexo服務，而 Docsify 并不需要構建靜態html文件，并且本地文件變更時網站會進行熱部署，自動的變更到本地3000端口實時展示，極大的減輕了我們對于網站的管理，能讓我們更加專注的進行文檔編寫或者知識的分享。
二、安裝 docsify
安裝 docsify 之前，我們需要安裝npm包管理器，而安裝了node.js就會自動安裝npm，對于node.js，直接去Node.js官網選擇合適的版本進行下載，然后一鍵安裝即可。
zhongsiru@zhongsirudeAir ~ % npm -v
8.3.2
接著我們來全局安裝 docsify-cli，這是一個 docsify 的命令行工具，可以幫助我們在本地進行 docsify 的初始化和網站的預覽。
npm i docsify-cli -g
然后我們創建一個文件夾，用來存儲 docsify 所有的文件，接著輸入以下命令進行初始化
mkdir docsify
docsify init ./docsify
可以看到初始化成功了，我們就可以在剛創建的 Docsify 文件夾中查看到README.md和index.html兩個文件，此外還存在一個隱藏文件.nojekyll
zhongsiru@zhongsirudeAir Documents % cd Docsify
zhongsiru@zhongsirudeAir Docsify % tree
.
├── README.md # 會做為主頁內容渲染
└── index.html # 入口文件
└── .nojekyll # 用于阻止 GitHub Pages 忽略掉下劃線開頭的文件
根據上述提示命令，我們便可啟動 docsify 的網站，默認在本地的3000端口
我們訪問該網址，便可以看到內容
這里渲染的內容就是上述 Docsify 文件夾中的 README.md，我們如果更改該文件中的內容，網站的內容會自動同步更新。
三、多頁文檔設置
我們可以輕松的在docsify 實現多級路由的網站，比如在前面創建的 Docsify 文件夾中創建guide.md、zh-cn/READEME.md、zh-cn/guide.md，結構如下所示：
.
├── README.md
├── guide.md
├── index.html
└── zh-cn├── README.md└── guide.md
此時我們訪問如下url即可以訪問到對應的頁面：
README.md => http://localhost:3000/#/
guide.md => http://localhost:3000/#/guide
/zh-cn/README.md => http://localhost:3000/#/zh-cn/
/zh-cn/guide.md => http://localhost:3000/#/zh-cn/guide
四、定制化配置
4.1、側邊欄
默認情況下，我們的側邊欄是根據 Markdown 文件自動生成，我們也可以定制化進行設定，首先修改Docsdify/index.html開啟側邊欄的選項添加loadSiderbar: true，這樣設置后就會加載 Docsify 目錄下的 _sidebar.md 文件進行加載而渲染成我們定制的側邊欄。
<script>window.$docsify = {name: '',repo: '',// 開啟側邊欄定制,加載_sidebar.mdloadSidebar: true,}
</script>
然后我們在 Docsify 目錄下創建一個 _sidebar.md 文件，里面可以對側邊欄進行配置，比如這里配置如下：
<!-- Docsify/_sidebar.md -->* [首頁](/)
* [guide](/guide)
* [zh-cn](zh-cn/)
* [zh-cn guide](zh-cn/guide)
也就是 MarkDown 中的超鏈接語法，后面的路徑也就對應著上述多頁文檔的路由路徑
這樣設置以后，渲染出的側邊欄如下圖所示，我們點擊對應地方即可跳轉到對應的多頁文檔
此外我們還可以指定頁面的標題，比如這里指定首頁的標題為home
<!-- Docsify/_sidebar.md -->* [首頁](/ "home")
* [guide](/guide)
* [zh-cn](zh-cn/)
* [zh-cn guide](zh-cn/guide)
📄 補充：嵌套的側邊欄
上述我們是在 Docsify 根目錄下新建了一個 _sidebar.md表示網站根路徑也就是默認3000端口路徑下的側邊欄樣式，但是 Docsify 是支持多頁文檔的，比如上述第3點中我們在根目錄下創建了 zh-cn 目錄，在這個目錄下又有兩個文件，我們也可以針對 zh-ch 這個目錄對應的路徑，定制化該目錄下的側邊欄。
例如我們在 Docsify/zh-cn目錄下創建一個 _sidebar.md，配置如下：
<!-- Docsify/zh-cn/_sidebar.md -->* [zh-ch首頁](/zh-cn)
* [zh-cn guide](zh-cn/guide)
測試我們首先進入3000端口的首頁
然后點擊 zh-cn 后，可以看到該目錄下的側邊欄，也就是上述配置的 Docsify/zh-cn/_sidebar.md
注意：
_sidebar.md的加載邏輯是從每層目錄下獲取文件，如果當前目錄不存在該文件則回退到上一級目錄。例如當前路徑為/zh-cn則從/zh-cn/_sidebar.md獲取文件，如果不存在則從/_sidebar.md獲取，我們也可以在 index.html 中如下配置表示默認都走根路徑下的_sidebar.md文件<script>window.$docsify = {loadSidebar: true,alias: {'/.*/_sidebar.md': '/_sidebar.md'}} </script>
📄 開啟側邊欄目錄
自定義側邊欄后默認不會再生成目錄，我們可以通過設置生成目錄的最大層級開啟這個功能：
<!-- index.html --><script>window.$docsify = {loadSidebar: true,// 開啟目錄,最大層級為2subMaxLevel: 2}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
當設置了 subMaxLevel 時，默認情況下每個標題都會自動添加到目錄中。如果你想忽略特定的標題，可以給它添加 <!-- {docsify-ignore} --> 。
# Getting Started## Header <!-- {docsify-ignore} -->該標題不會出現在側邊欄的目錄中。
要忽略特定頁面上的所有標題，你可以在頁面的第一個標題上使用 <!-- {docsify-ignore-all} --> 。
# Getting Started <!-- {docsify-ignore-all} -->## Header該標題不會出現在側邊欄的目錄中。
在使用時， <!-- {docsify-ignore} --> 和 <!-- {docsify-ignore-all} --> 都不會在頁面上呈現。
4.2、導航欄
添加導航欄有兩種方式，一是直接到 index.html 中添加，二是和側邊欄類似，通過 md 文件的形式來添加：
1?? html中添加nav標簽
<!-- index.html --><body><nav><a href="#/">EN</a><a href="#/zh-cn/">中文</a></nav>
</body>
2?? 通過md文件來添加
首先在 index.html 中配置 loadNavbar，默認加載的文件為 _navbar.md
<script>window.$docsify = {name: '',repo: '',loadSidebar: true,subMaxLevel: 3,// 開啟導航欄,加載_navbar.mdloadNavbar: true}</script>
然后在 Docsify 目錄下創建 _navbar.md，這樣設置與上述通過html的效果一致
<!-- _navbar.md -->* [En](/)
* [中文](/zh-cn/)
此外，如果導航內容過多，可以寫成嵌套的列表，會被渲染成下拉列表的形式：
<!-- _navbar.md -->* 入門* [快速開始](zh-cn/quickstart.md)* [多頁文檔](zh-cn/more-pages.md)* [定制導航欄](zh-cn/custom-navbar.md)* [封面](zh-cn/cover.md)* 配置* [配置項](zh-cn/configuration.md)* [主題](zh-cn/themes.md)* [使用插件](zh-cn/plugins.md)* [Markdown 配置](zh-cn/markdown.md)* [代碼高亮](zh-cn/language-highlight.md)
注意：
_navbar.md加載邏輯和sidebar文件一致，從每層目錄下獲取。例如當前路由為/zh-cn那么是從/zh-cn/_navbar.md獲取導航欄。
📄 整合自定義導航欄與 emoji 插件
如果你使用 emoji 插件:
<!-- index.html --><script>window.$docsify = {// ...}
</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>
例如，你可以在自定義導航欄 Markdown 文件中使用旗幟表情：
<!-- _navbar.md -->* 入門* [:us: 快速開始](zh-cn/quickstart.md)* [:uk: 多頁文檔](zh-cn/more-pages.md)* [:cn: 定制導航欄](zh-cn/custom-navbar.md)* [封面](zh-cn/cover.md)* 配置* [配置項](zh-cn/configuration.md)* [主題](zh-cn/themes.md)* [使用插件](zh-cn/plugins.md)* [Markdown 配置](zh-cn/markdown.md)* [代碼高亮](
4.3、封面
同側邊欄和導航欄一樣，我們手下在 index.html 中設置 coverpage 參數開啟封面功能
<script>window.$docsify = {name: '',repo: '',loadSidebar: true,subMaxLevel: 3,loadNavbar: true,// 開啟封面,加載_coverpage.mdcoverpage: true,}
</script>
然后在文檔根目錄創建 _coverpage.md 文件，用于配置封面內容
# docsify <small>3.5</small>> 一個神奇的文檔網站生成器。- 簡單、輕便 (壓縮后 ~21kB)
- 無需生成 html 文件
- 眾多主題[GitHub](https://github.com/docsifyjs/docsify/)
📄 自定義背景
目前的背景是隨機生成的漸變色，我們自定義背景色或者背景圖。在文檔末尾用添加圖片的 Markdown 語法設置背景。
<!-- 網站圖標 -->
# docsify <small>3.5</small>> 一個神奇的文檔網站生成器。- 簡單、輕便 (壓縮后 ~21kB)
- 無需生成 html 文件
- 眾多主題[GitHub](https://github.com/docsifyjs/docsify/)<!-- 背景圖片 -->
<!-- 背景色 -->
📄 多封面
如果你的文檔網站是多語言的，或許你需要設置多個封面，例如你的文檔目錄結構如下
.
└── docs├── README.md├── guide.md├── _coverpage.md└── zh-cn├── README.md└── guide.md└── _coverpage.md
那么可以這樣配置
window.$docsify = {coverpage: ['/', '/zh-cn/']
};
4.4、主題
目前支持的主題如下所示，我們只需要在 index.html 中引入想要的主題即可
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dolphin.css">
五、部署
以上就是 docsify 的一個基本的配置，更多的配置可以查看docsify官方文檔根據自己的情況作出定制化修改，接下來我們將這個網站部署上線使得所有人都可以進行訪問，以下分別介紹了部署到 Gitee Page 和部署到云服務兩種方式。
5.1、部署到Gitee
我們在gitee上新建一個倉庫Docsify
然后 git clone 到本地，然后在其中創建一個docs目錄，然后把本地的 Docsify 目錄拷貝到該目錄中
# 1.克隆倉庫
git clone https://gitee.com/bareth/docsify.git# 2.進入倉庫
cd docsify # 3.創建docs目錄并進入
mkdir docs&cd docs # 4.將本地docsify文件拷貝到docs目錄
mv ~/Documents/Docsify .
然后我們重新將本地變更推送到 gitee 遠程倉庫中
git add .
git commit -m "add docsify files"
git push
然后我們填寫要部署的目錄
最后就生成了一個網站地址，我們點擊直接可以訪問了
5.2、部署到云服務器
這里我們采用 Nginx 反向代理服務器來部署，首先在云服務器上安裝好 Nginx：Nginx最新版安裝教程（Windows+Linux）
Nginx 安裝完成后，我們訪問服務器的公網ip即可進入nginx頁面
接下來我們在 Nginx 安裝目錄也就是 /usr/local/nginx 下新建一個文件夾專門用來存放 Docsify 的文件
接下來我們將本地存放docsify文件的 Docsify 文件夾上傳到服務器的 Docsify 文件夾即可
scp -r Docsify root@139.198.40.248:/usr/local/nginx/Docsify
此時 docsify 相關文件已經上傳到 nginx 的 Docsify 目錄中，接下來我們將該路徑配置到 nginx 配置文件中即可
vim /usr/local/nginx/conf/nginx.conf
將 location/root 地址更改為存放 docsify 文件的 Docsify 目錄的地址即可，更改完保存退出
然后我們重啟 nginx 服務器
/usr/local/nginx/sbin/nginx -s reload
完成后我們再次訪問服務器的公網ip即可看到 docsify 的網站
總結
以上是生活随笔為你收集整理的Docsify个人网站搭建详细教程的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： Golang的交叉编译问题
- 下一篇： Hexo集成Algolia实现搜索功能