【工具】10分鐘快速搭建屬于自己的文檔網(wǎng)站

前言

很多同學(xué)都希望能夠擁有自己的一個(gè)文檔系統(tǒng)，去記錄/總結(jié)自己所學(xué)到的知識(shí)。

本文就來(lái)介紹一下 Docsify^[1] + Github Page 的方式，旨在快速搭建屬于自己的文檔網(wǎng)站

本文的 Demo 代碼可以通過(guò) https://github.com/GpingFeng/docsify-demo 查看，演示看 https://gpingfeng.github.io/docsify-demo/#/

準(zhǔn)備工作

全局安裝 docsify-cli 工具，并創(chuàng)建文檔項(xiàng)目目錄

npm i docsify-cli -g
mkdir my-docs
cd my-docs

初始化項(xiàng)目

docsify init ./docs

成功后會(huì)生成一個(gè) docs 的文件夾，并且里面有三個(gè)文件

• index.html 入口文件。后面我們的配置很多都是在這里配置
• README.md 會(huì)做為主頁(yè)內(nèi)容渲染
• .nojekyll 用于阻止 GitHub Pages 忽略掉下劃線開(kāi)頭的文件

啟動(dòng)項(xiàng)目

docsify serve docs

通過(guò)運(yùn)行 docsify serve 啟動(dòng)一個(gè)本地服務(wù)器，可以方便地實(shí)時(shí)預(yù)覽效果。默認(rèn)訪問(wèn)地址 http://localhost:3000^[2] 。下面的內(nèi)容時(shí)間上是 README.md 中的內(nèi)容

簡(jiǎn)單的配置

接下來(lái)就是配置我們的文檔了

配置側(cè)邊欄

在 index.html 中，新增配置 loadSidebar: true

window.$docsify = {
  name: '',
  repo: '',
+  loadSidebar: true
}

在 docs 中新建一個(gè)文件 _sidebar.md，寫入

- JavaScript
  - [閉包](closure.md "閉包")
  - [原型](prototype.md "原型")

- CSS
  - [布局](layout.md "布局")

同時(shí)在 docs 中新建 closure.md 、prototype.md和 layout.md三個(gè) Markdown 文件

可以在 closure.md 中寫入如下，查看效果

# 介紹閉包
## 什么是閉包
哈哈哈哈

## 閉包的作用是什么

自動(dòng)生成目錄

可以根據(jù)標(biāo)題生成目錄，這個(gè)在文章很長(zhǎng)的時(shí)候很有用，直接演示配置和效果

window.$docsify = {
  name: '',
  repo: '',
  loadSidebar: true,
+ subMaxLevel: 2
}

插件的使用

基礎(chǔ)的配置已經(jīng)完成了，當(dāng)然還有其他更多的功能配置，這里不再細(xì)說(shuō)。Docsify 還提供了豐富的插件，接下來(lái)我們看看

全文搜索

配置非常簡(jiǎn)單

<script>
  window.$docsify = {
    name: '',
    repo: '',
    loadSidebar: true,
    subMaxLevel: 2,
+   search: 'auto'
  }
</script>
<!-- Docsify v4 -->
<script src="http://cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

查看效果

圖片縮放

Docsify 是需要插件才能實(shí)現(xiàn)圖片縮放的，但其實(shí)也很簡(jiǎn)單，如下

    <script>
      window.$docsify = {
        name: '',
        repo: '',
        loadSidebar: true,
        subMaxLevel: 2,
        search: 'auto'
      }
    </script>
    <!-- Docsify v4 -->
    <script src="http://cdn.jsdelivr.net/npm/docsify@4"></script>
    <script src="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
+   <script src="http://cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>

支持 CodePen 插入

隨便找到一個(gè) CodePen，打開(kāi)，找到 Embed，點(diǎn)擊進(jìn)入

點(diǎn)擊 iframe,copy 里面的代碼。粘貼到你的 markdown 文件中

就可以查看 CodePen 的了

更多的插件實(shí)現(xiàn)方案

Docsify 還提供了 Gitalk^[3] 評(píng)論插件等。更多請(qǐng)看官方文檔^[4]，這里不再贅述。

部署

你不需要一臺(tái)服務(wù)器（當(dāng)然也可以），我們直接部署到 Github Page 中。先上傳我們的代碼到 Github。這里不再演示這一步，請(qǐng)讀者自行完成

找到 Settings

找到 GitHub Pages，選擇 main 和 docs 文件夾，點(diǎn)擊 save

稍等一會(huì)，就會(huì)生成我們的文檔地址了，可以點(diǎn)擊這里^[5]查看本文的演示效果

總結(jié)

本文從 0 到 1 介紹以 Docsify^[6] + Github Page 的方式，快速搭建屬于自己的文檔系統(tǒng)，并部署到線上。當(dāng)然文章提到的只是 Docsify 的一小部分功能，趕興趣的可以去官方^[7]查看

參考資料