2018-07-01 07:27:01 -04:00
|
|
|
|
# 服务端渲染（SSR）
|
|
|
|
|
|
|
|
|
|
|
|
先看例子 https://docsify.now.sh
|
|
|
|
|
|
|
|
|
|
|
|
项目地址在 https://github.com/docsifyjs/docsify-ssr-demo
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
文档依旧是部署在 GitHub Pages 上，Node 服务部署在 now.sh 里，渲染的内容是从 GitHub Pages 上同步过来的。所以静态部署文档的服务器和服务端渲染的 Node 服务器是分开的，也就是说你还是可以用之前的方式更新文档，并不需要每次都部署。
|
|
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
## 什么是 SSR?
|
|
|
|
|
|
- 更好的 SEO
|
|
|
|
|
|
- 更酷的感觉
|
2018-07-01 07:27:01 -04:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 快速开始
|
|
|
|
|
|
|
|
|
|
|
|
如果你熟悉 `now` 的使用，接下来的介绍就很简单了。先创建一个新项目，并安装 `now` 和 `docsify-cli`。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
npm i now docsify-cli -D
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
编辑 `package.json`。假设你的文档放在 `./docs` 子目录。
|
2018-07-01 07:27:01 -04:00
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
2020-04-26 01:54:44 -04:00
|
|
|
|
"name": "my-project",
|
2018-07-01 07:27:01 -04:00
|
|
|
|
"scripts": {
|
2020-04-26 01:54:44 -04:00
|
|
|
|
"start": "docsify start . -c ssr.config.js",
|
2018-07-01 07:27:01 -04:00
|
|
|
|
"deploy": "now -p"
|
|
|
|
|
|
},
|
2020-04-26 01:54:44 -04:00
|
|
|
|
"files": [
|
|
|
|
|
|
"docs"
|
|
|
|
|
|
],
|
2018-07-01 07:27:01 -04:00
|
|
|
|
"docsify": {
|
|
|
|
|
|
"config": {
|
|
|
|
|
|
"basePath": "https://docsify.js.org/",
|
|
|
|
|
|
"loadSidebar": true,
|
2020-04-26 01:54:44 -04:00
|
|
|
|
"loadNavbar": true,
|
|
|
|
|
|
"coverpage": true,
|
|
|
|
|
|
"name": "docsify"
|
2018-07-01 07:27:01 -04:00
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
如果你还没有创建文档，可以参考[之前的文章](https://zhuanlan.zhihu.com/p/24540753)。
|
2018-07-01 07:27:01 -04:00
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
!> 其中 `basePath` 相当于 webpack 的 `publicPath ，为文档所在的路径，可以填你的 docsify 文档网站。我们可以使用本地或者远程文件。
|
2018-07-01 07:27:01 -04:00
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
配置好了以后，我们可以在本地预览。
|
2018-07-01 07:27:01 -04:00
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
```bash
|
|
|
|
|
|
npm start
|
|
|
|
|
|
|
|
|
|
|
|
# open http://localhost:4000
|
2018-07-01 07:27:01 -04:00
|
|
|
|
```
|
|
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
Publish it!
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
now -p
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Now, You have a support for SSR the docs site.
|
|
|
|
|
|
|
|
|
|
|
|
## 定制模板
|
|
|
|
|
|
|
|
|
|
|
|
你可以提供一个整页模板，例如：
|
2018-07-01 07:27:01 -04:00
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
|
<!DOCTYPE html>
|
|
|
|
|
|
<html lang="en">
|
|
|
|
|
|
<head>
|
|
|
|
|
|
<meta charset="UTF-8">
|
|
|
|
|
|
<title>docsify</title>
|
|
|
|
|
|
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
|
2020-04-26 01:54:44 -04:00
|
|
|
|
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" title="vue">
|
2018-07-01 07:27:01 -04:00
|
|
|
|
</head>
|
|
|
|
|
|
<body>
|
|
|
|
|
|
<!--inject-app-->
|
|
|
|
|
|
<!--inject-config-->
|
2020-04-26 01:54:44 -04:00
|
|
|
|
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.js"></script>
|
|
|
|
|
|
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.js"></script>
|
|
|
|
|
|
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-bash.min.js"></script>
|
|
|
|
|
|
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-markdown.min.js"></script>
|
|
|
|
|
|
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-nginx.min.js"></script>
|
2018-07-01 07:27:01 -04:00
|
|
|
|
</body>
|
|
|
|
|
|
</html>
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
模板可以包含占位符，会自动将渲染后的 html 和配置内容注入到页面上。
|
2018-07-01 07:27:01 -04:00
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
- `<!--inject-app-->`
|
|
|
|
|
|
- `<!--inject-config-->`
|
2018-07-01 07:27:01 -04:00
|
|
|
|
|
|
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
## 配置
|
|
|
|
|
|
|
|
|
|
|
|
配置可以单独写在配置文件内，然后通过 `--config config.js` 加载，或者写在 `package.json` 中。
|
|
|
|
|
|
|
|
|
|
|
|
渲染的基础模版也可以自定义，配置在 `template` 属性上。
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
module.exports = {
|
|
|
|
|
|
template: './ssr.html',
|
|
|
|
|
|
maxAge: 60 * 60 * 1000, // lru-cache 设置
|
|
|
|
|
|
config: {
|
|
|
|
|
|
// docsify 设置
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
2018-07-01 07:27:01 -04:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
|
2018-07-01 07:27:01 -04:00
|
|
|
|
## 更多玩法
|
|
|
|
|
|
|
2020-04-26 01:54:44 -04:00
|
|
|
|
你可以直接在你的 Node 服务器上执行 `docsify start` 。
|
|
|
|
|
|
|
2018-07-01 07:27:01 -04:00
|
|
|
|
`docsify start` 其实是依赖了 [`docsify-server-renderer`](https://npmarket.surge.sh/?name=docsify-server-renderer) 模块，如果你感兴趣，你完全可以用它自己实现一个 server，可以加入缓存等功能。
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
var Renderer = require('docsify-server-renderer')
|
|
|
|
|
|
var readFileSync = require('fs').readFileSync
|
|
|
|
|
|
|
|
|
|
|
|
// init
|
|
|
|
|
|
var renderer = new Renderer({
|
2020-04-26 01:54:44 -04:00
|
|
|
|
template: readFileSync('./docs/index.template.html', 'utf-8'),
|
2018-07-01 07:27:01 -04:00
|
|
|
|
config: {
|
|
|
|
|
|
name: 'docsify',
|
|
|
|
|
|
repo: 'docsifyjs/docsify'
|
|
|
|
|
|
}
|
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
|
|
renderer.renderToString(url)
|
|
|
|
|
|
.then(html => {})
|
|
|
|
|
|
.catch(err => {})
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
当然文档文件和 server 也是可以部署在一起的，`basePath` 不是一个 URL 的话就会当做文件路径处理，也就是从服务器上加载资源。
|
