2018-02-23 11:56:51 +08:00
|
|
|
# Server-Side Rendering
|
2017-05-30 03:48:29 +08:00
|
|
|
|
2022-01-24 11:42:58 +08:00
|
|
|
!> :construction: SSR support is experimental and incomplete. We are working on it. Plugins and
|
|
|
|
|
some features of Docsify will not work in SSR mode yet. :construction:
|
|
|
|
|
|
|
|
|
|
<!--
|
|
|
|
|
This link is dead.
|
2017-05-30 03:48:29 +08:00
|
|
|
See https://docsify.now.sh
|
2022-01-24 11:42:58 +08:00
|
|
|
-->
|
2017-05-30 11:54:37 +08:00
|
|
|
|
2022-01-24 11:42:58 +08:00
|
|
|
Sample repo at https://github.com/docsifyjs/docsify-ssr-demo
|
2017-05-31 08:35:01 +08:00
|
|
|
|
2017-05-30 11:54:37 +08:00
|
|
|
## Why SSR?
|
2022-01-24 11:42:58 +08:00
|
|
|
|
2017-05-30 11:54:37 +08:00
|
|
|
- Better SEO
|
|
|
|
|
- Feeling cool
|
|
|
|
|
|
|
|
|
|
## Quick start
|
|
|
|
|
|
2017-05-30 12:55:09 +08:00
|
|
|
Install `now` and `docsify-cli` in your project.
|
2017-05-30 11:54:37 +08:00
|
|
|
|
|
|
|
|
```bash
|
2017-05-31 08:35:01 +08:00
|
|
|
npm i now docsify-cli -D
|
2017-05-30 11:54:37 +08:00
|
|
|
```
|
|
|
|
|
|
2021-07-31 00:37:52 +08:00
|
|
|
Edit `package.json`. The below assumes the documentation is in the `./docs` subdirectory.
|
2017-05-30 11:54:37 +08:00
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"name": "my-project",
|
|
|
|
|
"scripts": {
|
2017-05-31 08:35:01 +08:00
|
|
|
"start": "docsify start . -c ssr.config.js",
|
|
|
|
|
"deploy": "now -p"
|
2017-05-30 11:54:37 +08:00
|
|
|
},
|
|
|
|
|
"files": [
|
|
|
|
|
"docs"
|
|
|
|
|
],
|
|
|
|
|
"docsify": {
|
|
|
|
|
"config": {
|
2018-01-12 12:54:07 +08:00
|
|
|
"basePath": "https://docsify.js.org/",
|
2017-05-30 11:54:37 +08:00
|
|
|
"loadSidebar": true,
|
|
|
|
|
"loadNavbar": true,
|
|
|
|
|
"coverpage": true,
|
|
|
|
|
"name": "docsify"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2017-05-31 08:35:01 +08:00
|
|
|
!> The `basePath` just like webpack `publicPath`. We can use local or remote files.
|
2017-05-30 11:54:37 +08:00
|
|
|
|
2021-07-31 00:37:52 +08:00
|
|
|
We can preview the local site to see if it works.
|
2017-05-30 11:54:37 +08:00
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
npm start
|
|
|
|
|
|
|
|
|
|
# open http://localhost:4000
|
|
|
|
|
```
|
|
|
|
|
|
2017-05-30 12:55:09 +08:00
|
|
|
Publish it!
|
2017-05-30 11:54:37 +08:00
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
now -p
|
|
|
|
|
```
|
|
|
|
|
|
2021-07-31 00:37:52 +08:00
|
|
|
Now, you have support for SSR.
|
2017-05-30 11:54:37 +08:00
|
|
|
|
|
|
|
|
## Custom template
|
|
|
|
|
|
2021-07-31 00:37:52 +08:00
|
|
|
You can provide a template for an entire page's HTML, such as
|
2017-05-30 11:54:37 +08:00
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
<!DOCTYPE html>
|
|
|
|
|
<html lang="en">
|
|
|
|
|
<head>
|
|
|
|
|
<meta charset="UTF-8">
|
|
|
|
|
<title>docsify</title>
|
2020-04-28 04:47:49 +08:00
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
|
2020-02-12 19:40:23 +08:00
|
|
|
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" title="vue">
|
2017-05-30 11:54:37 +08:00
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
<!--inject-app-->
|
|
|
|
|
<!--inject-config-->
|
2020-02-12 19:40:23 +08: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>
|
2017-05-30 11:54:37 +08:00
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The template should contain these comments for rendered app content.
|
|
|
|
|
- `<!--inject-app-->`
|
|
|
|
|
- `<!--inject-config-->`
|
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
You can configure it in a special config file, or `package.json`.
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
module.exports = {
|
2017-05-30 15:41:34 +08:00
|
|
|
template: './ssr.html',
|
2017-12-29 16:45:32 +08:00
|
|
|
maxAge: 60 * 60 * 1000, // lru-cache config
|
2017-05-30 11:54:37 +08:00
|
|
|
config: {
|
|
|
|
|
// docsify config
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Deploy for your VPS
|
|
|
|
|
|
|
|
|
|
You can run `docsify start` directly on your Node server, or write your own server app with `docsify-server-renderer`.
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
var Renderer = require('docsify-server-renderer')
|
|
|
|
|
var readFileSync = require('fs').readFileSync
|
|
|
|
|
|
|
|
|
|
// init
|
|
|
|
|
var renderer = new Renderer({
|
2019-01-06 07:26:21 +08:00
|
|
|
template: readFileSync('./docs/index.template.html', 'utf-8'),
|
2017-05-30 11:54:37 +08:00
|
|
|
config: {
|
|
|
|
|
name: 'docsify',
|
2018-07-01 13:48:44 +08:00
|
|
|
repo: 'docsifyjs/docsify'
|
2017-05-30 11:54:37 +08:00
|
|
|
}
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
renderer.renderToString(url)
|
|
|
|
|
.then(html => {})
|
|
|
|
|
.catch(err => {})
|
|
|
|
|
```
|
