docsify - 無需構建快速生成文檔網站

時間 2019-11-06

標籤 docsify 無需構建快速生成文檔網站欄目網站開發简体版

原文原文鏈接

docsify

無需構建快速生成文檔頁css

網站：https://github.com/qingwei-li...
文檔：https://docsify.js.org/zh-cnhtml

特性

無需構建，寫完 markdown 直接發佈vue
支持自定義主題git
容易使用而且輕量github

快速上手

建立項目

新建一個空項目，接着建立一個 docs 目錄並進入到 docs 目錄下shell

mkdir my-project && cd my-project
mkdir docs && cd docs

建立入口文件

建立一個 404.html 文件，內容爲npm

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
</body>
<script src="//unpkg.com/docsify"></script>
</html>

新建 README.md 文件，做爲主頁面json

# Title

## balabala

部署！

將項目 push 到 GitHub 倉庫後到設置頁面開啓 GitHub Pages 功能，選擇 docs/ 選項
服務器

命令行工具

方便快速建立文檔目錄，會讀取項目的 package.json 裏的選項做爲 docsify 的配置，支持本地預覽。markdown

安裝

npm i docsify-cli -g

初始化文檔

默認初始化在當前目錄，推薦將文檔放在 docs 目錄下

docsify init docs

啓動本地服務

啓動一個 server 方便預覽，打開 http://localhost:3000

docsify serve docs

更多選項參考 docsify-cli

主題

目前提供 vue.css 和 buble.css，直接修改 404.html 裏的 cdn 地址便可

<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css">

壓縮版

<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css">

更多功能

多頁面

README.md 做爲主頁面，若是須要其餘頁面，直接在文檔目錄下建立對應的 *.md 文件，例如建立一個 guide.md 那麼對應的路由就是 /guide。

配置參數

repo

參考本文檔的右上角的 GitHub 圖標，若是要開啓的話，將 404.html 裏的 script 改爲

<script src="//unpkg.com/docsify" data-repo="your/repo"></script>

max-level

目錄最大展開層級，默認值爲 6

<script src="//unpkg.com/docsify" data-max-level="6"></script>

el

替換節點元素，默認爲 #app

<script src="//unpkg.com/docsify" data-el="#app"></script>

sidebar-toggle

Sidebar 開關按鈕

<script src="//unpkg.com/docsify" data-sidebar-toggle></script>

sidebar

設置後 TOC 功能將不可用，適合導航較多的文檔，data-sidebar 傳入全局變量名。

<script>
  window.sidebar = [
    { slug: '/', title: 'Home' },
    {
      slug: '/pageA',
      title: 'page A',
      children: [
        { slug: '/pageA/childrenB', title: 'children B' }
      ]
    },
    { slug: '/PageC', title: 'Page C' }
  ]
</script>
<script src="/lib/docsify.js" data-sidebar="sidebar"></script>

load-sidebar

讀取側邊欄配置文件，若是配置，默認加載當前目錄下的 _sidebar.md。若是文件不存在，會顯示 TOC 做爲側邊欄內容。若是你有二級目錄，也應該放置一份配置文件。

<script src="/lib/docsify.js" data-load-sidebar></script>

你能夠指定側邊欄文件名

<script src="/lib/docsify.js" data-load-sidebar="_sidebar.md"></script>

_sidebar.md 的內容能夠是這樣的

- [Home](/)
- [Installation](/installation)
- Essentials
  - [Getting Started](/getting-started)
  - [Dynamic Route Matching](/dynamic-matching)
  - [Nested Routes](/nested-routes)
  - [Programmatic Navigation](/navigation)
  - [Named Routes](/named-routes)
  - [Named Views](/named-views)
  - [Redirect and Alias](/redirect-and-alias)
  - [HTML5 History Mode](/history-mode)

load-navbar

讀取導航配置文件，若是配置，默認加載當前目錄下的 _navbar.md。若是文件不存在，會顯示 html 裏定義的導航欄。

<script src="/lib/docsify.js" data-load-navbar></script>

你能夠指定導航欄文件名

<script src="/lib/docsify.js" data-load-navbar="_navbar.md"></script>

_navbar.md 的內容能夠是這樣

- [en](/)
- [中文](/zh-cn)

固然也支持二級列表，將生成一個下拉列表

- [download](/download)
- language
  - [en](/)
  - [中文](/zh-cn)

FAQ

爲何是 `404.html` 而不用 `index.html`

docsify 想要實現的是用最簡單的方式 動態渲染內容。

例如我有兩個文檔分別爲 README.md 和 guide.md，若是我用 index.html 做爲文件名，README.md 能夠被正確的渲染由於咱們已經規定它爲首頁文件，可是若是咱們訪問 my-domain.com/guide 想要獲得的結果是 guide.md 的內容，它將沒法工做，由於目錄下並不存在一個 guide.html 的文件。

可是 GitHub Pages 服務器找不到資源，就會回退並渲染 404.html 文件。?

網站：https://github.com/qingwei-li...
文檔：https://docsify.js.org/zh-cn