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

前言

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

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

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

準備工作

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

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

初始化項目

docsify init ./docs

成功后會生成一個 docs 的文件夾，并且里面有三個文件

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

啟動項目

docsify serve docs

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

簡單的配置

接下來就是配置我們的文檔了

配置側(cè)邊欄

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

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

在 docs 中新建一個文件 _sidebar.md，寫入

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

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

同時在 docs 中新建 closure.md 、prototype.md和 layout.md三個 Markdown 文件

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

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

## 閉包的作用是什么

自動生成目錄

可以根據(jù)標題生成目錄，這個在文章很長的時候很有用，直接演示配置和效果

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

插件的使用

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

全文搜索

配置非常簡單

<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 是需要插件才能實現(xià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 插入

隨便找到一個 CodePen，打開，找到 Embed，點擊進入

點擊 iframe,copy 里面的代碼。粘貼到你的 markdown 文件中

就可以查看 CodePen 的了

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

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

部署

你不需要一臺服務器（當然也可以），我們直接部署到 Github Page 中。先上傳我們的代碼到 Github。這里不再演示這一步，請讀者自行完成

找到 Settings

找到 GitHub Pages，選擇 main 和 docs 文件夾，點擊 save

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

總結(jié)

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

參考資料