mirror of
https://gitee.com/docsifyjs/docsify.git
synced 2024-11-30 11:08:58 +08:00
docs(ssr): update
This commit is contained in:
qingwei.li
parent
3b74c49f00
commit
1938fd5146
@ -2,6 +2,8 @@
|
||||
|
||||
See https://docsify.now.sh
|
||||
|
||||
Repo in https://github.com/QingWei-Li/docsify-ssr-demo
|
||||
|
||||
## Why SSR?
|
||||
- Better SEO
|
||||
- Feeling cool
|
||||
@ -11,24 +13,24 @@ See https://docsify.now.sh
|
||||
Install `now` and `docsify-cli` in your project.
|
||||
|
||||
```bash
|
||||
npm i now -g
|
||||
npm i docsify-cli -D
|
||||
npm i now docsify-cli -D
|
||||
```
|
||||
|
||||
Edit `package.json`. If the documentation in `./docs` subdirectory.
|
||||
Edit `package.json`. If the documentation in `./docs` subdirectory.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-project",
|
||||
"scripts": {
|
||||
"start": "docsify start ."
|
||||
"start": "docsify start . -c ssr.config.js",
|
||||
"deploy": "now -p"
|
||||
},
|
||||
"files": [
|
||||
"docs"
|
||||
],
|
||||
"docsify": {
|
||||
"config": {
|
||||
"basePath": "/docs/",
|
||||
"basePath": 'https://docsify.js.org/',
|
||||
"loadSidebar": true,
|
||||
"loadNavbar": true,
|
||||
"coverpage": true,
|
||||
@ -38,10 +40,7 @@ npm i docsify-cli -D
|
||||
}
|
||||
```
|
||||
|
||||
Remove `index.html`
|
||||
|
||||
|
||||
!> The `basePath` just like webpack `publicPath`. You should config it if your docs is in the subdirectory.
|
||||
!> The `basePath` just like webpack `publicPath`. We can use local or remote files.
|
||||
|
||||
We can preview in the local to see if it works.
|
||||
|
||||
|
||||
14
docs/ssr.md
14
docs/ssr.md
@ -2,6 +2,8 @@
|
||||
|
||||
See https://docsify.now.sh
|
||||
|
||||
Repo in https://github.com/QingWei-Li/docsify-ssr-demo
|
||||
|
||||
## Why SSR?
|
||||
- Better SEO
|
||||
- Feeling cool
|
||||
@ -11,8 +13,7 @@ See https://docsify.now.sh
|
||||
Install `now` and `docsify-cli` in your project.
|
||||
|
||||
```bash
|
||||
npm i now -g
|
||||
npm i docsify-cli -D
|
||||
npm i now docsify-cli -D
|
||||
```
|
||||
|
||||
Edit `package.json`. If the documentation in `./docs` subdirectory.
|
||||
@ -21,14 +22,15 @@ Edit `package.json`. If the documentation in `./docs` subdirectory.
|
||||
{
|
||||
"name": "my-project",
|
||||
"scripts": {
|
||||
"start": "docsify start ."
|
||||
"start": "docsify start . -c ssr.config.js",
|
||||
"deploy": "now -p"
|
||||
},
|
||||
"files": [
|
||||
"docs"
|
||||
],
|
||||
"docsify": {
|
||||
"config": {
|
||||
"basePath": "/docs/",
|
||||
"basePath": 'https://docsify.js.org/',
|
||||
"loadSidebar": true,
|
||||
"loadNavbar": true,
|
||||
"coverpage": true,
|
||||
@ -38,9 +40,7 @@ Edit `package.json`. If the documentation in `./docs` subdirectory.
|
||||
}
|
||||
```
|
||||
|
||||
Remove `index.html`
|
||||
|
||||
!> The `basePath` just like webpack `publicPath`. You should config it if your docs is in the subdirectory.
|
||||
!> The `basePath` just like webpack `publicPath`. We can use local or remote files.
|
||||
|
||||
We can preview in the local to see if it works.
|
||||
|
||||
|
||||
@ -1,67 +1,61 @@
|
||||
# Server client renderer
|
||||
# 服务端渲染（SSR）
|
||||
|
||||
See https://docsify.now.sh
|
||||
先看例子 https://docsify.now.sh
|
||||
|
||||
## Why SSR?
|
||||
- Better SEO
|
||||
- Feeling cool
|
||||
项目地址在 https://github.com/QingWei-Li/docsify-ssr-demo
|
||||
|
||||
## Quick start
|
||||
|
||||
|
||||
Install `now` and `docsify-cli` in your project.
|
||||
文档依旧是部署在 GitHub Pages 上，Node 服务部署在 now.sh 里，渲染的内容是从 GitHub Pages 上同步过来的。所以静态部署文档的服务器和服务端渲染的 Node 服务器是分开的，也就是说你还是可以用之前的方式更新文档，并不需要每次都部署。
|
||||
|
||||
|
||||
|
||||
## 快速开始
|
||||
|
||||
如果你熟悉 `now` 的使用，接下来的介绍就很简单了。先创建一个新项目，并安装 `now` 和 `docsify-cli`。
|
||||
|
||||
```bash
|
||||
npm i now -g
|
||||
npm i docsify-cli -D
|
||||
mkdir my-ssr-demo && cd my-ssr-demo
|
||||
npm init -y
|
||||
npm i now docsify-cli -D
|
||||
```
|
||||
|
||||
2. Edit `package.json`. If the documentation in `./docs` subdirectory.
|
||||
配置 `package.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-project",
|
||||
"scripts": {
|
||||
"start": "docsify start ."
|
||||
"start": "docsify start .",
|
||||
"deploy": "now -p"
|
||||
},
|
||||
"files": [
|
||||
"docs"
|
||||
],
|
||||
"docsify": {
|
||||
"config": {
|
||||
"basePath": "/docs/",
|
||||
"basePath": "https://docsify.js.org/",
|
||||
"loadSidebar": true,
|
||||
"loadNavbar": true,
|
||||
"coverpage": true,
|
||||
"name": "docsify"
|
||||
"loadNavbar": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你还没有创建文档，可以参考[之前的文章](https://zhuanlan.zhihu.com/p/24540753)。其中 `basePath` 为文档所在的路径，可以填你的 docsify 文档网站。
|
||||
|
||||
Remove `index.html`
|
||||
配置可以单独写在配置文件内，然后通过 `--config config.js` 加载。
|
||||
|
||||
!> The `basePath` just like webpack `publicPath`. You should config it if your docs is in the subdirectory.
|
||||
渲染的基础模版也可以自定义，配置在 `template` 属性上，例如
|
||||
|
||||
We can preview in the local to see if it works.
|
||||
|
||||
```bash
|
||||
npm start
|
||||
|
||||
# open http://localhost:4000
|
||||
```js
|
||||
"docsify": {
|
||||
"template": "./ssr.html",
|
||||
"config": {
|
||||
"basePath": "https://docsify.js.org/",
|
||||
"loadSidebar": true,
|
||||
"loadNavbar": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Publish it!
|
||||
|
||||
```bash
|
||||
now -p
|
||||
```
|
||||
|
||||
Now, You have a support for SSR the docs site.
|
||||
|
||||
## Custom template
|
||||
|
||||
You can provide a templte for entire page's HTML. such as
|
||||
*ssr.html*
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
@ -69,41 +63,39 @@ You can provide a templte for entire page's HTML. such as
|
||||
<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/themes/vue.css" title="vue">
|
||||
<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.js"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
|
||||
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
|
||||
<script src="//unpkg.com/prismjs/components/prism-markdown.min.js"></script>
|
||||
<script src="//unpkg.com/prismjs/components/prism-nginx.min.js"></script>
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
|
||||
</html>
|
||||
|
||||
```
|
||||
|
||||
The template should contain these comments for rendered app content.
|
||||
- `<!--inject-app-->`
|
||||
- `<!--inject-config-->`
|
||||
其中 `<!--inject-app-->` 和 `<!--inject-config-->` 为占位符，会自动将渲染后的 html 和配置内容注入到页面上。
|
||||
|
||||
## Configuration
|
||||
现在，你可以运行 `npm start` 预览效果，如果没有问题就通过 `npm run deploy` 部署服务。
|
||||
|
||||
You can configure it in a special config file, or `package.json`.
|
||||
```bash
|
||||
npm start
|
||||
# open http://localhost:4000
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
template: './ssr.html',
|
||||
config: {
|
||||
// docsify config
|
||||
}
|
||||
}
|
||||
npm run deploy
|
||||
# now ...
|
||||
```
|
||||
|
||||
## Deploy for your VPS
|
||||
|
||||
You can run `docsify start` directly on your Node server, or write your own server app with `docsify-server-renderer`.
|
||||
|
||||
## 更多玩法
|
||||
|
||||
`docsify start` 其实是依赖了 [`docsify-server-renderer`](https://npmarket.surge.sh/?name=docsify-server-renderer) 模块，如果你感兴趣，你完全可以用它自己实现一个 server，可以加入缓存等功能。
|
||||
|
||||
```js
|
||||
var Renderer = require('docsify-server-renderer')
|
||||
@ -122,3 +114,5 @@ renderer.renderToString(url)
|
||||
.then(html => {})
|
||||
.catch(err => {})
|
||||
```
|
||||
|
||||
当然文档文件和 server 也是可以部署在一起的，`basePath` 不是一个 URL 的话就会当做文件路径处理，也就是从服务器上加载资源。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user