Docsify生成文檔網站

時間 2020-04-25

標籤 docsify 生成文檔網站欄目網站開發简体版

原文原文鏈接

Docsify生成文檔網站

1. docsify簡介

docsify 是一個動態生成文檔網站的工具。不一樣於 GitBook、Hexo 的地方是它不會生成將 .md 轉成 .html 文件，全部轉換工做都是在運行時進行。javascript

docsify能你快速的搭建一個小型的文檔網站，只須要建立一個 index.html 就能夠開始寫文檔並且直接部署在 GitHub Pages。css

官方文檔：https://docsify.js.org/#/html

官方github: https://github.com/docsifyjs/docsify/vue

2. docsify入門案例

開啓docsify第一個案例，須要安裝Node.js以及docsify-cli工具。java

2.1 安裝Node.js

下載地址：https://nodejs.org/dist/v8.9.4/node-v8.9.4-x64.msi
下載完成後點擊安裝。
查看node 版本，命令：node -v

2.2 docsify-cli

docsify-cli是生成docsify項目的小工具。使用如下命令全局安裝docsify-cli，安裝完成查看版本node

#全局安裝docsify-cli
npm i docsify-cli -g

#查看版本
docsify -v

2.3 初始化項目

建立一個項目根目錄,用來存放案例git

mkdir docsifyDemo

進入項目根目錄並初始化github

docsify init ./docs

查看生成的目錄和文件spring

tree /f

生成目錄和文件sql

─docs
--.nojekyll   用於阻止 GitHub Pages 會忽略掉下劃線開頭的文件
--index.html  入口文件
--README.md   主頁內容渲染

2.4 啓動項目

運行服務

docsify serve ./docs

默認訪問

http://localhost:3000

訪問效果

3. docsify 實戰

3.1 設置封面

在docs/index.html中添加封面設置

<script>
    window.$docsify = {
      coverpage: true
    }
 </script>

建立docs/_coverpage.md，並添加如下內容

![logo](https://docsify.js.org/_media/icon.svg)

# Spring Security 從零開始的異世界
### 從零開始學 Spring Security
> 以Spring Security爲主題，開啓學習之旅，從基本案例到實戰案例

[Gitee](https://gitee.com/newbetome/spring-security-fromzero)
[Get Started](README.md)

刷新頁面，查看效果

3.2 設置內容

在docs/README.md中設置內容，默認狀況下，側邊欄會根據當前文檔的標題生成目錄。

## 1. Spring Security 簡介
簡介
## 2. Spring Security 入門程序
入門程序
## 3. 表單認證
表單認證
### 3.1 HTTP Basic認證
HTTP Basic認證
### 3.2 HttpClient模擬Basic認證
HttpClient模擬Basic認證

查看效果，總體知足使用，可是美中不足，須要自定義側邊欄等。

3.3 定製側邊欄

在docs/README.md中設置:loadSidebar: true

<script>
    window.$docsify = {
      name: 'Spring Security Study',//側邊欄標題
      repo: '',//github地址
      loadSidebar: true, // 加載自定義側邊欄
      maxLevel: 4, // 默認狀況下會抓取文檔中全部標題渲染成目錄，可配置最大支持渲染的標題層級。
      subMaxLevel: 5, // 生成目錄的最大層級
      mergeNavbar: true, // 小屏設備下合併導航欄到側邊欄
      alias: { // 定義路由別名，能夠更自由的定義路由規則。 支持正則
        '/.*/_sidebar.md': '/_sidebar.md'//防止意外回退
      },
    coverpage: true//設置封面
    }
  </script>

建立_sidebar.md文件配置側邊欄

* Spring Security 學習篇
    * [Spring Security 整合JDBC](mypages/1.md)
    *[Spring Security 整合Druid](mypages/2.md)
    *[Spring Security 整合Druid](mypages/3.md)

分別建立docs/mypages/1.md、docs/mypages/2.md、docs/mypages/3.md，內容一致

# 標題1
## 標題1.1
# 標題2
## 標題2.1

查看效果

3.4 頂部導航欄

建立docs/_navbar.md配置頂部導航欄

* 學習
  * [文檔1]()
  * [文檔2]()

* 插件
  * [插件2]()
  * [學習教程]()

在docs/index.html添加

loadNavbar: true,//頂部導航

完整docs/index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Document</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="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'Spring Security Study',//側邊欄標題
      repo: 'https://gitee.com/newbetome/spring-security-fromzero',//github地址
      loadNavbar: true,//頂部導航
      loadSidebar: true, // 加載自定義側邊欄
      maxLevel: 4, // 默認狀況下會抓取文檔中全部標題渲染成目錄，可配置最大支持渲染的標題層級。
      subMaxLevel: 5, // 生成目錄的最大層級
      mergeNavbar: true, // 小屏設備下合併導航欄到側邊欄
      alias: { // 定義路由別名，能夠更自由的定義路由規則。 支持正則
        '/.*/_sidebar.md': '/_sidebar.md'//防止意外回退
      },
      coverpage: true//設置封面
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

</body>
</html>

查看效果

4. 插件

4.1代碼高亮

在docs/index.html添加

<script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-java.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-sql.js"></script>

4.1 代碼拷貝

在docs/index.html添加

<script src="//unpkg.com/docsify-copy-code"></script>

4.2 圖片放大

在docs/index.html添加

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>

4.3 全文搜索

在docs/index.html添加樣式

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

默認搜索

<script>
    window.$docsify = {
     search: 'auto', // default
    }
 </script>

自定義搜索

<script>
    window.$docsify = {
      search: {
        placeholder: '搜索',
        noData: '找不到結果!',
        depth: 3
      },
    }
 </script>

5. 部署

建立項目，提交項目，設置gitHub pages

一、master分支
二、master分支下的docs目錄
三、gh-pages分支

一、在項目根目錄寫的，直接把代碼推送到master分支上， GitHub Pages裏選擇master branch.
2.文檔是在master分支下的docs/目錄下編寫的，直接把代碼推送到master分支上，GitHub Pages裏選擇master branch/docs folder.

最終代碼：https://github.com/fby2018/MyDocsify

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。