jyapayne/docsify
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(ssr): update

Browse source
This commit is contained in:
qingwei.li 2017-05-31 08:35:01 +08:00
commit 1938fd5146
No known key found for this signature in database
GPG key ID: B6DDC2F7AE80B2F4
3 changed files with 67 additions and 74 deletions
Download patch file Download diff file Expand all files Collapse all files

15
docs/de-de/ssr.md
View file

@ -2,6 +2,8 @@
See https://docsify.now.sh See https://docsify.now.sh
Repo in https://github.com/QingWei-Li/docsify-ssr-demo
## Why SSR? ## Why SSR?
- Better SEO - Better SEO
- Feeling cool - Feeling cool
@ -11,8 +13,7 @@ See https://docsify.now.sh
Install `now` and `docsify-cli` in your project. Install `now` and `docsify-cli` in your project.
```bash ```bash
npm i now -g npm i now docsify-cli -D
npm i docsify-cli -D
``` ```
Edit `package.json`. If the documentation in `./docs` subdirectory. Edit `package.json`. If the documentation in `./docs` subdirectory.
@ -21,14 +22,15 @@ npm i docsify-cli -D
{ {
"name": "my-project", "name": "my-project",
"scripts": { "scripts": {
"start": "docsify start ." "start": "docsify start . -c ssr.config.js",
"deploy": "now -p"
}, },
"files": [ "files": [
"docs" "docs"
], ],
"docsify": { "docsify": {
"config": { "config": {
"basePath": "/docs/", "basePath": 'https://docsify.js.org/',
"loadSidebar": true, "loadSidebar": true,
"loadNavbar": true, "loadNavbar": true,
"coverpage": true, "coverpage": true,
@ -38,10 +40,7 @@ npm i docsify-cli -D
} }
``` ```
Remove `index.html` !> The `basePath` just like webpack `publicPath`. We can use local or remote files.
!> The `basePath` just like webpack `publicPath`. You should config it if your docs is in the subdirectory.
We can preview in the local to see if it works. We can preview in the local to see if it works.

14
docs/ssr.md
View file

@ -2,6 +2,8 @@
See https://docsify.now.sh See https://docsify.now.sh
Repo in https://github.com/QingWei-Li/docsify-ssr-demo
## Why SSR? ## Why SSR?
- Better SEO - Better SEO
- Feeling cool - Feeling cool
@ -11,8 +13,7 @@ See https://docsify.now.sh
Install `now` and `docsify-cli` in your project. Install `now` and `docsify-cli` in your project.
```bash ```bash
npm i now -g npm i now docsify-cli -D
npm i docsify-cli -D
``` ```
Edit `package.json`. If the documentation in `./docs` subdirectory. 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", "name": "my-project",
"scripts": { "scripts": {
"start": "docsify start ." "start": "docsify start . -c ssr.config.js",
"deploy": "now -p"
}, },
"files": [ "files": [
"docs" "docs"
], ],
"docsify": { "docsify": {
"config": { "config": {
"basePath": "/docs/", "basePath": 'https://docsify.js.org/',
"loadSidebar": true, "loadSidebar": true,
"loadNavbar": true, "loadNavbar": true,
"coverpage": 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`. We can use local or remote files.
!> The `basePath` just like webpack `publicPath`. You should config it if your docs is in the subdirectory.
We can preview in the local to see if it works. We can preview in the local to see if it works.

110
docs/zh-cn/ssr.md
View file

@ -1,67 +1,61 @@
# Server client renderer # 服务端渲染（SSR）
See https://docsify.now.sh 先看例子 https://docsify.now.sh
## Why SSR? 项目地址在 https://github.com/QingWei-Li/docsify-ssr-demo
- Better SEO
- Feeling cool
## Quick start ![](https://dn-mhke0kuv.qbox.me/2bfef08c592706108055.png)
Install `now` and `docsify-cli` in your project. 文档依旧是部署在 GitHub Pages 上，Node 服务部署在 now.sh 里，渲染的内容是从 GitHub Pages 上同步过来的。所以静态部署文档的服务器和服务端渲染的 Node 服务器是分开的，也就是说你还是可以用之前的方式更新文档，并不需要每次都部署。
## 快速开始
如果你熟悉 `now` 的使用，接下来的介绍就很简单了。先创建一个新项目，并安装 `now` 和 `docsify-cli`。
```bash ```bash
npm i now -g mkdir my-ssr-demo && cd my-ssr-demo
npm i docsify-cli -D npm init -y
npm i now docsify-cli -D
``` ```
2. Edit `package.json`. If the documentation in `./docs` subdirectory. 配置 `package.json`
```json ```json
{ {
"name": "my-project",
"scripts": { "scripts": {
"start": "docsify start ." "start": "docsify start .",
"deploy": "now -p"
}, },
"files": [
"docs"
],
"docsify": { "docsify": {
"config": { "config": {
"basePath": "/docs/", "basePath": "https://docsify.js.org/",
"loadSidebar": true, "loadSidebar": true,
"loadNavbar": true, "loadNavbar": true
"coverpage": true,
"name": "docsify"
} }
} }
} }
``` ```
如果你还没有创建文档，可以参考[之前的文章](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. ```js
"docsify": {
```bash "template": "./ssr.html",
npm start "config": {
"basePath": "https://docsify.js.org/",
# open http://localhost:4000 "loadSidebar": true,
"loadNavbar": true
}
}
``` ```
Publish it! *ssr.html*
```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
```html ```html
<!DOCTYPE html> <!DOCTYPE html>
@ -69,41 +63,39 @@ You can provide a templte for entire page's HTML. such as
<head> <head>
<meta charset="UTF-8"> <meta charset="UTF-8">
<title>docsify</title> <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"> <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> </head>
<body> <body>
<!--inject-app--> <!--inject-app-->
<!--inject-config--> <!--inject-config-->
</body> </body>
<script src="//unpkg.com/docsify/lib/docsify.js"></script> <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script> <script src="//unpkg.com/docsify/lib/plugins/search.min.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>
</html> </html>
``` ```
The template should contain these comments for rendered app content. 其中 `<!--inject-app-->` 和 `<!--inject-config-->` 为占位符，会自动将渲染后的 html 和配置内容注入到页面上。
- `<!--inject-app-->`
- `<!--inject-config-->`
## 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 npm run deploy
module.exports = { # now ...
template: './ssr.html',
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`.
## 更多玩法
`docsify start` 其实是依赖了 [`docsify-server-renderer`](https://npmarket.surge.sh/?name=docsify-server-renderer) 模块，如果你感兴趣，你完全可以用它自己实现一个 server，可以加入缓存等功能。
```js ```js
var Renderer = require('docsify-server-renderer') var Renderer = require('docsify-server-renderer')
@ -122,3 +114,5 @@ renderer.renderToString(url)
.then(html => {}) .then(html => {})
.catch(err => {}) .catch(err => {})
``` ```
当然文档文件和 server 也是可以部署在一起的，`basePath` 不是一个 URL 的话就会当做文件路径处理，也就是从服务器上加载资源。