服务端渲染(SSR)

先看例子 https://docsify.now.sh

项目地址在 https://github.com/QingWei-Li/docsify-ssr-demo

服务端渲染 (SSR) - 图1

文档依旧是部署在 GitHub Pages 上,Node 服务部署在 now.sh 里,渲染的内容是从 GitHub Pages 上同步过来的。所以静态部署文档的服务器和服务端渲染的 Node 服务器是分开的,也就是说你还是可以用之前的方式更新文档,并不需要每次都部署。

快速开始

如果你熟悉 now 的使用,接下来的介绍就很简单了。先创建一个新项目,并安装 nowdocsify-cli

  1. mkdir my-ssr-demo && cd my-ssr-demo
  2. npm init -y
  3. npm i now docsify-cli -D

配置 package.json

  1. {
  2. "scripts": {
  3. "start": "docsify start .",
  4. "deploy": "now -p"
  5. },
  6. "docsify": {
  7. "config": {
  8. "basePath": "https://docsify.js.org/",
  9. "loadSidebar": true,
  10. "loadNavbar": true
  11. }
  12. }
  13. }

如果你还没有创建文档,可以参考之前的文章。其中 basePath 为文档所在的路径,可以填你的 docsify 文档网站。

配置可以单独写在配置文件内,然后通过 --config config.js 加载。

渲染的基础模版也可以自定义,配置在 template 属性上,例如

  1. "docsify": {
  2. "template": "./ssr.html",
  3. "config": {
  4. "basePath": "https://docsify.js.org/",
  5. "loadSidebar": true,
  6. "loadNavbar": true
  7. }
  8. }

ssr.html

  1. <!DOCTYPE html>
  2. <html lang="en">
  3. <head>
  4. <meta charset="UTF-8">
  5. <title>docsify</title>
  6. <link rel="icon" href="_media/favicon.ico">
  7. <meta name="keywords" content="doc,docs,documentation,gitbook,creator,generator,github,jekyll,github-pages">
  8. <meta name="description" content="A magical documentation generator.">
  9. <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  10. <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css" title="vue">
  11. </head>
  12. <body>
  13. <!--inject-app-->
  14. <!--inject-config-->
  15. </body>
  16. <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  17. <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
  18. </html>

其中 <!--inject-app--><!--inject-config--> 为占位符,会自动将渲染后的 html 和配置内容注入到页面上。

现在,你可以运行 npm start 预览效果,如果没有问题就通过 npm run deploy 部署服务。

  1. npm start
  2. # open http://localhost:4000
  3. npm run deploy
  4. # now ...

更多玩法

docsify start 其实是依赖了 docsify-server-renderer 模块,如果你感兴趣,你完全可以用它自己实现一个 server,可以加入缓存等功能。

  1. var Renderer = require('docsify-server-renderer')
  2. var readFileSync = require('fs').readFileSync
  3. // init
  4. var renderer = new Renderer({
  5. template: readFileSync('./docs/index.template.html', 'utf-8').,
  6. config: {
  7. name: 'docsify',
  8. repo: 'qingwei-li/docsify'
  9. }
  10. })
  11. renderer.renderToString(url)
  12. .then(html => {})
  13. .catch(err => {})

当然文档文件和 server 也是可以部署在一起的,basePath 不是一个 URL 的话就会当做文件路径处理,也就是从服务器上加载资源。