docsify 4.0 釋出，支援服務端渲染（SSR）

Cinwell發表於2019-03-04
服務端

docsify 是一個無需編譯輕量級的文件生成工具，從釋出到現在已經有半年多。經歷了 110 個版本迭代，在 GitHub 收穫 2k 多 stars，能搜尋的資料顯示有 300 多個專案正在使用 docsify。

docsify 可以讓你只需將 md 文件直接部署在 GitHub Pages 然後建立一個 index.html 檔案，將工具通過 script 標籤引入即可。少量的配置就讓你擁有一份精緻的文件網站。

這本來是一個我拿來做實驗的專案，所以能想到比較有意思的特性都會加進去。比如利用 CSS 變數特性做主題色定製、前段時間很火的 PWA 我也嘗試性的加入、還有為 docsify 開發的 vue 程式碼編輯和預覽的工具 vuep。今天我要宣佈一個新特性——服務端渲染（SSR）。

效果

先看例子 docsify.now.sh

docsify 4.0 釋出，支援服務端渲染（SSR）

文件依舊是部署在 GitHub Pages 上，Node 服務部署在 now.sh 裡，渲染的內容是從 GitHub Pages 上同步過來的。所以靜態部署文件的伺服器和服務端渲染的 Node 伺服器是分開的，也就是說你還是可以用之前的方式更新文件，並不需要每次都部署。

快速開始

如果你熟悉 now 的使用，接下來的介紹就很簡單了。先建立一個新專案，並安裝 now 和 docsify-cli。

mkdir my-ssr-demo && cd my-ssr-demo
npm init -y
npm i now docsify-cli -D複製程式碼

配置 package.json

{
  "scripts": {
    "start": "docsify start .",
    "deploy": "now -p"
  },
  "docsify": {
    "config": {
      "basePath": "https://docsify.js.org/",
      "loadSidebar": true,
      "loadNavbar": true
    }
  }
}複製程式碼

如果你還沒有建立文件，可以參考之前的文章。其中 basePath 為文件所在的路徑，可以填你的 docsify 文件網站。

配置可以單獨寫在配置檔案內，然後通過 --config config.js 載入。

渲染的基礎模版也可以自定義，配置在 template 屬性上，例如

"docsify": {
      "template": "./ssr.html",
    "config": {
      "basePath": "https://docsify.js.org/",
      "loadSidebar": true,
      "loadNavbar": true
    }
  }複製程式碼

ssr.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>docsify</title>
  <link rel="icon" href="_media/favicon.ico">
  <meta name="keywords" content="doc,docs,documentation,gitbook,creator,generator,github,jekyll,github-pages">
  <meta name="description" content="A magical documentation generator.">
  <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" title="vue">
</head>
<body>
  <!--inject-app-->
  <!--inject-config-->
</body>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
</html>複製程式碼

其中 <!--inject-app--> 和 <!--inject-config--> 為佔位符，會自動將渲染後的 html 和配置內容注入到頁面上。

現在，你可以執行 npm start 預覽效果，如果沒有問題就通過 npm run deploy 部署服務。

npm start
# open http://localhost:4000

npm run deploy
# now ...複製程式碼

更多玩法

docsify start 其實是依賴了 docsify-server-renderer 模組，如果你感興趣，你完全可以用它自己實現一個 server，可以加入快取等功能。

var Renderer = require('docsify-server-renderer')
var readFileSync = require('fs').readFileSync

// init
var renderer = new Renderer({
  template: readFileSync('./docs/index.template.html', 'utf-8').,
  config: {
    name: 'docsify',
    repo: 'qingwei-li/docsify'
  }
})

renderer.renderToString(url)
  .then(html => {})
  .catch(err => {})複製程式碼

當然文件檔案和 server 也是可以部署在一起的，basePath 不是一個 URL 的話就會當做檔案路徑處理，也就是從伺服器上載入資源。

最後最後

docsify 4.0 釋出，支援服務端渲染（SSR）

紀念下這特殊的版本 ?，一晚上實現外加一白天修 bug，還特麼是在生日的時候。SSR 都支援了，編譯靜態檔案也不遠了，嗯。

如果你覺得 docsify 對你有幫助，或者想對我微小的工作一點資瓷，歡迎給我捐贈。

相關文章