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

本文轉載自查看原文 2022-01-16 22:32 33804 【Docsify】

前言

　　網上關於動態文檔生成工具有很多如：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,
            /*搜索相關設置*/
            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://mp.weixin.qq.com/s/dCyKG6n6l5ICTl24dKNqbw) 
  * [博客園地址](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部署教程👉