Docsify使用指南（打造最快捷、最輕量級的個人&團隊文件）

追逐時光者發表於2022-01-16

前言

　　網上關於動態文件生成工具有很多如：Docsify、 VuePress、Docute 、Hexo這些都是一些非常優秀的文件生成工具，本章主要介紹如何快速使用Docsify搭建一個快捷、輕量級的個人&團隊文件。

什麼是Docsify？

　　一個神奇的文件網站生成器。docsify 可以快速幫你生成文件網站。不同於 GitBook、Hexo 的地方是它不會生成靜態的 .html 檔案，所有轉換工作都是在執行時。如果你想要開始使用它，只需要建立一個 index.html 就可以開始編寫文件。

Docsify的特性

  • 無需構建，寫完文件直接釋出
  • 容易使用並且輕量 (壓縮後 ~21kB)
  • 智慧的全文搜尋
  • 提供多套主題
  • 豐富的 API
  • 支援 Emoji
  • 相容 IE11
  • 支援服務端渲染 SSR (示例)

輕量&完善的Docsify模板

　　該模板為一個簡潔，並且完善的Docsify模板基本上可以滿足百分之八十多的團隊需求，你可以按照文章中的Docsify環境配置教程把執行Docsify所需要的環境配置起來，通過命令即可檢視效果（配置環境順利的話只要十來分鐘）。

模板原始碼地址：Docsify-Guide?

模板預覽地址：https://ysgstudyhards.github.io/Docsify-Guide/#/?

Node.js 安裝配置

win+r：cmd進入命令提示符視窗，分別輸入以下命令檢視node和npm的版本能夠正常顯示版本號，則安裝成功：

  • node -v：顯示安裝的nodejs版本
  • npm -v：顯示安裝的npm版本

docsify-cli工具安裝

推薦全域性安裝 docsify-cli 工具，可以方便地建立及在本地預覽生成的文件。

npm i docsify-cli -g

專案初始化

如果想在專案的 ./docs(檔名可以按自己的想法來) 目錄裡寫文件，直接通過 init 初始化專案。

docsify init ./Docsify-Guide

初始化成功後，可以看到 ./docs 目錄下建立的幾個檔案

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

直接編輯 docs/README.md 就能更新文件內容，當然也可以新增更多頁面。

本地執行docsify建立的專案

通過執行 docsify serve 專案名稱 啟動一個本地伺服器，可以方便地實時預覽效果。預設訪問地址 http://localhost:3000 。

docsify serve Docsify-Guide

基礎配置檔案介紹

其實我們維護一份輕量級的個人&團隊文件我們只需要配置以下這幾個基本檔案就可以了。

檔案作用檔案
基礎配置項（入口檔案） index.html
封面配置檔案 _coverpage.md
側邊欄配置檔案 _sidebar.md
導航欄配置檔案 _navbar.md
主頁內容渲染檔案 README.md
瀏覽器圖示 favicon.ico

基礎配置項（index.html）

下面是一份基礎的配置項模板如下(可直接Copy使用)。

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>Docsify-Guide</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="description" content="Description">
    <meta name="viewport"
        content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <!-- 設定瀏覽器圖示 -->
    <link rel="icon" href="/favicon.ico" type="image/x-icon" />
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" />
    <!-- 預設主題 -->
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>

<body>
    <!-- 定義載入時候的動作 -->
    <div id="app">載入中...</div>
    <script>
        window.$docsify = {
            // 專案名稱
            name: 'Docsify-Guide',
            // 倉庫地址，點選右上角的Github章魚貓頭像會跳轉到此地址
            repo: 'https://github.com/YSGStudyHards',
            // 側邊欄支援，預設載入的是專案根目錄下的_sidebar.md檔案
            loadSidebar: true,
            // 導航欄支援，預設載入的是專案根目錄下的_navbar.md檔案
            loadNavbar: true,
            // 封面支援，預設載入的是專案根目錄下的_coverpage.md檔案
            coverpage: true,
            // 最大支援渲染的標題層級
            maxLevel: 5,
            // 自定義側邊欄後預設不會再生成目錄，設定生成目錄的最大層級（建議配置為2-4）
            subMaxLevel: 4,
            // 小屏裝置下合併導航欄到側邊欄
            mergeNavbar: true,
        }
    </script>
    <script>
        // 搜尋配置(url：https://docsify.js.org/#/zh-cn/plugins?id=%e5%85%a8%e6%96%87%e6%90%9c%e7%b4%a2-search)
        window.$docsify = {
            search: {
                maxAge: 86400000,// 過期時間，單位毫秒，預設一天
                paths: auto,// 注意：僅適用於 paths: 'auto' 模式
                placeholder: '搜尋',
                // 支援本地化
                placeholder: {
                    '/zh-cn/': '搜尋',
                    '/': 'Type to search'
                },
                noData: '找不到結果',
                depth: 4,
                hideOtherSidebarContent: false,
                namespace: 'Docsify-Guide',
            }
        }
    </script>
    <!-- docsify的js依賴 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
    <!-- emoji表情支援 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
    <!-- 圖片放大縮小支援 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
    <!-- 搜尋功能支援 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
    <!--在所有的程式碼塊上新增一個簡單的Click to copy按鈕來允許使用者從你的文件中輕易地複製程式碼-->
    <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
</body>

</html>

封面配置檔案（_coverpage.md）

Docsify官網封面配置教程

index.html

<!-- index.html -->

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

_coverpage.md

<!-- _coverpage.md -->

# Docsify使用指南 

> ?Docsify使用指南，使用Typora+Docsify打造最強、最輕量級的個人&團隊文件。

 簡單、輕便 (壓縮後 ~21kB)
- 無需生成 html 檔案
- 眾多主題


[開始使用 Let Go](/README.md)

側邊欄配置檔案（_sidebar.md）

Docsify官網配置側邊欄教程

index.html

<!-- index.html -->

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

在index.html基礎配置檔案中設定了二級目錄

_sidebar.md

<!-- _sidebar.md -->

* Typora+Docsify使用指南
  * [Docsify使用指南](/ProjectDocs/Docsify使用指南.md) <!--注意這裡是相對路徑-->
  * [Typora+Docsify快速入門](/ProjectDocs/Typora+Docsify快速入門.md)
* Docsify部署
  * [Docsify部署教程](/ProjectDocs/Docsify部署教程.md)

導航欄配置檔案（_navbar.md）

Docsify官網配置導航欄教程

index.html

<!-- index.html -->

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

_navbar.md

<!-- _navbar.md -->

* 連結到我
  * [部落格園地址](https://www.cnblogs.com/Can-daydayup/)
  * [Github地址](https://github.com/YSGStudyHards)
  * [知乎地址](https://www.zhihu.com/people/ysgdaydayup)
  * [掘金地址](https://juejin.cn/user/2770425031690333/posts)
  * [Gitee地址](https://gitee.com/ysgdaydayup)


* 友情連結
  * [Docsify](https://docsify.js.org/#/)
  * [部落格園](https://www.cnblogs.com/)

全文搜尋 - Search

全文搜尋 - Search?

Docsify主題切換

注意：切換主題只需要在根目錄的index.html切換對應的主題css檔案即可

詳情參考：https://docsify.js.org/#/zh-cn/themes?

Docsify詳細部署教程

Docsify部署教程?

相關教程

 

相關文章