chore: update docs

ly525
1 parent c56da70a
Showing 4 changed files with 139 additions and 118 deletions
docs/.vuepress/config.js
docs/zh/ecosystem/backend-intergration.md
docs/zh/getting-started/features.md
docs/zh/getting-started/quick-start.md
@@ -180,6 +180,11 @@ module.exports = {
     // reference: https://github.com/vuejs/vuepress/issues/1435
     'dehydrate': {}
   },
+  markdown: {
+    extendMarkdown: md => {
+      md.use(require('markdown-it-task-lists'))
+    }
+  },
   // plugins: [
   //   [
   //     '@vuepress/google-analytics',
 # 后端集成说明
+[[toc]]
  
 ## 需求
-- 将鲁班H5 编辑器后端模块 由Node.js  换成 Java(Spring Boot)/PHP 等其它后端语言
+- 鲁班H5 后端(Node.js)  ->  Java(Spring Boot)/PHP 等
  
 ## 解决方案
 > 目前鲁班H5的后端是基于 Node.js 写的，社区的很多小伙伴反馈，希望能够提供 Spring Boot 或者 PHP 等其它语言驱动的后端API。因为精力有限，我们提供了如下的解决方案，来尝试解决这个需求：
@@ -13,19 +14,10 @@
     - [springboot2-mybatis-plus-api-for-luban](https://github.com/luban-h5/springboot2-mybatis-plus-api-for-luban) ![GitHub stars](https://img.shields.io/github/stars/luban-h5/springboot2-mybatis-plus-api-for-luban.svg?style=social&label=Star&maxAge=2592000) ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)
  
 - WIP: Working in Progress 迭代中
-- 版权声明：鲁班H5 版权所有，禁止任何形式的转载和抄袭，侵权必
+- 版权声明：鲁班H5 版权所有，禁止任何形式的转载和抄袭，侵权必究
  
-## 贡献代码或自行开发
-### 前提准备
-
-1. 了解鲁班H5 编辑器的后端 Model
-1. 了解鲁班H5 编辑器的后端 接口
-
----
  
-
-
-## 数据库表/Table(Model/Entity class) + 字段说明
+## 数据库表
  
 ### Work 表：H5 作品
  
@@ -399,3 +391,8 @@ WorkForm Table 结构
  
 ```
  
+## 贡献代码或自行开发
+### 前提准备
+
+1. 了解鲁班H5 编辑器的后端 Model
+1. 了解鲁班H5 编辑器的后端 接口
 # Features
+[[toc]]
  
 ### 编辑器
 - [x] 参考线
 # 快速开始
+
+[[toc]]
+
 - 重要：关于此部分有疑惑，请在下面直接评论，或者到[社区](https://support.qq.com/products/93432/)讨论
 - 如果您已经熟悉并已经安装了 `Node`、`Yarn`，可以直接参照下面的命令，快速上手
 - 如果您不熟悉，请阅读下面的详细教程
  
-## 快速体验
-> 以下三种方式，任选其中一种即可
+## 技术栈(当前)
+
+::: warning
+- 推荐采用 Node LTS (v10 or V12)
+- 安装完成后， 如果遇到接口 403 问题，请看：[#_2-注意事项](#_2-注意事项)
+:::
+
+::: details Node、Yarn 等基础概念
+> 首先你需要大概了解下 Node.js 的相关生态、Node.js 的安装
+我们接下来会花几分钟介绍一下基础概念. 我们默认你知道 Linux 和 Git 的基本操作
+#### Node.js、npm、nvm
+
+1. `Node.js` 
+    - 服务器端的JavaScript 运行环境，你可以理解为和Python、Java等一样，它也是一门后端语言
+1. `npm(or yarn)` Node.js 的包版本工具
+    - 类似于 Python 的pip，或 Centos 的yum，或 Ubuntu 的 apt-get
+    - 你在python 中安装requrest 库，通常是通过 `pip install requests` 来安装
+    - 在 Node.js 中，也是一样的，只是把 `pip` 换成 `pip` or `yarn` 即可： `npm install requests`  or `yarn add requests` 
+3. `nvm` ：Node.js 版本工具
+    -  使用 nvm可以快速安装 Node 的某个版本，比如通过 `node -v` 查看你的Node 当前版本。
+    -  假如这个版本(假设当前版本为 v.8.0.0)不符合要求，你可以通过 `nvm install v10.15.3` 来安装 `v10.15.3` 
+
+#### Node、Yarn、npm 安装
+1. 请参照 [Strapi 的 预安装文档指导](https://strapi.io/documentation/3.0.0-beta.x/getting-started/install-requirements.html#installation-requirements) ，安装 Node、npm 和 Yarn
+1. 因为 yarn 的仓库源在海外，所以，请配置国内镜像源，提高速度
+
+```bash
+yarn config get registry
+# -> https://registry.yarnpkg.com
+
+# 改成 taobao 的源：
+yarn config set registry https://registry.npm.taobao.org
+# -> yarn config v0.15.0
+# -> success Set "registry" to "https://registry.npm.taobao.org".
+
+# 看到 succes 表示安装完毕
+```
+:::
+
+- 前端：[Vue.js](https://cn.vuejs.org/)
+- 后端：[Strapi](https://strapi.io/)
+- 存储：Sqlite/Mysql
+
  
-#### 一、一键脚本（推荐！）
+
+## 本地快速上手
+::: tip
+以下三种方式，任选其中一种即可
+:::
+
+### 一、一键脚本（推荐）
 ```bash
 git clone https://github.com/ly525/luban-h5 && cd luban-h5
 # 安装依赖，构建前后端（安装依赖会耗时略长，请耐心等待）
@@ -18,12 +68,8 @@ git clone https://github.com/ly525/luban-h5 &amp;&amp; cd luban-h5
 # ./luban-h5.sh stop
 ```
  
-- 更多细节，请参照 [鲁班H5-在线文档](https://ly525.github.io/luban-h5/zh/) 的 [`快速开始`](https://ly525.github.io/luban-h5/zh/getting-started/quick-start.html) 章节，进行配置即可
-
-- 如果遇到接口 403 问题，请参照 [`快速开始`](https://ly525.github.io/luban-h5/zh/getting-started/quick-start.html) 章节，搜索关键字：403 即可
-
-
-#### 二、本地安装了 Node、Yarn
+### 二、本地安装了 Node、Yarn
+> 适合 熟悉前端开发的同学、使用 Windows 的同学
 ```bash
 git clone https://github.com/ly525/luban-h5
 cd luban-h5 # 项目根目录
@@ -39,7 +85,9 @@ cd front-end/h5 &amp;&amp; yarn &amp;&amp; yarn build:engine &amp;&amp; yarn dev
 - 更多细节，请参照 [鲁班H5-在线文档](https://ly525.github.io/luban-h5/zh/) 的 [`快速开始`](https://ly525.github.io/luban-h5/zh/getting-started/quick-start.html) 章节，进行配置即可
  
  
-#### 三、熟悉 Docker（迭代中，不推荐使用，后期会推出docker image）
+### 三、熟悉 Docker
+> 迭代中，不推荐使用，后期会推出docker image，欢迎提 Pull Request
+::: details 点击查看
 > 使用官方提供的 [***一键安装脚本***](https://raw.githubusercontent.com/ly525/luban-h5/dev/deploy/ubuntu-install.sh)，简化安装步骤，在本地通过使用 `Docker+Ubuntu 镜像`，即可`快速安装+体验` 鲁班H5
  
 > [快速体验-完整文档](https://github.com/ly525/luban-h5/wiki/Quick-Start(%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89%8B%E7%AF%87)%EF%BC%9ADocker-Ubuntu-Image-for-Quick-Local-Dev)，简而言之：
@@ -59,65 +107,46 @@ wget -qO- https://raw.githubusercontent.com/ly525/luban-h5/dev/deploy/ubuntu-ins
 # 2. 鲁班前端
 # 2.1 宿主机访问 「鲁班前端」：localhost:1234, 即可看到鲁班的前端
 ```
+:::
  
-
-# 常见问题
-> 这部分一般是按照下面的教程运行之后，仍然可能会遇到的问题。比较适合粗心、文档只看了一半、比较着急的同学
-
-1. 接口 `403 Forbidden`，解决方案看这里：[#_2-注意事项](#_2-注意事项)
-2. 弹框中的 `预览页面显示空白`，解决方案看这里：[2. 构建预览所需的渲染引擎](#_2-构建预览所需的渲染引擎)
-
-
-# 视频教程
-<iframe src="//player.bilibili.com/player.html?aid=76827615&cid=131403430&page=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" width="100%" height="600"> </iframe>
-
-## 基础概念
-> 首先你需要大概了解下 Node.js 的相关生态、Node.js 的安装
-我们接下来会花几分钟介绍一下基础概念. 我们默认你知道 Linux 和 Git 的基本操作
-### Node.js、npm、nvm
-
-1. `Node.js` 
- 服务器端的JavaScript 运行环境，你可以理解为和Python、Java等一样，它也是一门后端语言
-1. `npm(or yarn)` Node.js 的包版本工具
-> 1. 类似于 Python 的pip，或 Centos 的yum，或 Ubuntu 的 apt-get
-> 1. 你在python 中安装requrest 库，通常是通过 `pip install requests` 来安装
-> 1. 在 Node.js 中，也是一样的，只是把 `pip` 换成 `pip` or `yarn` 即可： `npm install requests`  or `yarn add requests` 
-
-
-3. `nvm` ：Node.js 版本工具
-> 1. 使用 nvm可以快速安装 Node 的某个版本，比如通过 `node -v` 查看你的Node 当前版本。
-> 1. 假如这个版本(假设当前版本为 v.8.0.0)不符合要求，你可以通过 `nvm install v10.15.3` 来安装 `v10.15.3` 
-
-
-### Node、Yarn、npm 安装
-
-1. 请参照 [Strapi 的 预安装文档指导](https://strapi.io/documentation/3.0.0-beta.x/getting-started/install-requirements.html#installation-requirements) ，安装 Node、npm 和 Yarn
-1. 因为 yarn 的仓库源在海外，所以，请配置国内镜像源，提高速度
+## 详细教程
+### 前端
+#### 1. 快速上手
  
 ```bash
-yarn config get registry
-# -> https://registry.yarnpkg.com
-
-# 改成 taobao 的源：
-yarn config set registry https://registry.npm.taobao.org
-# -> yarn config v0.15.0
-# -> success Set "registry" to "https://registry.npm.taobao.org".
+# 默认当前位置目录为 luban-h5 项目的根目录
+cd front-end/h5 && yarn && yarn build:engine && yarn dev
  
-# 看到 succes 表示安装完毕
+# 更多命令请参见 project/front-end/h5/package.json
 ```
  
-## 技术栈(当前)
-- 前端：Vue.js
-- 后端：Strapi
-- 存储：Sqlite
-
-# 项目环境搭建
-> 鲁班H5的后端接口，由 [Strapi.js](https://github.com/strapi/strapi/) 驱动
-
-## 后端环境搭建
-> 如果遇到接口 403 问题，请看：[#_2-注意事项](#_2-注意事项)
-### 1. 快速上手
+#### 2. 构建预览所需的渲染引擎
+::: tip 所谓的渲染引擎是什么？
+- 鲁班H5 编辑一个作品在服务端保存的其实是一个 JSON，相关原理参见：[如何将JSON转换成手机端网页?](https://www.yuque.com/luban-h5/docs/ug7xg5)，那么谁来把 JSON -> H5 页面呢？
+- 答案：JSON -> ”渲染引擎“ -> H5页面（也就是说，“渲染引擎” 担当了 将 json 渲染为H5页面的重任）
+- 使用场景：预览页面、用户最终看到H5页面
+- 源码地址：`luban-h5/front-end/h5/src/engine-entry.js`
+:::
  
+####  如何构建
+1. 在`front-end/h5`目录下，运行：`yarn build:engine`
+2. 构建完成之后，后端的`h5-api/public`里面会多一个文件夹 `engine-assets`（即渲染引擎）
+
+#### 相关原理
+- 源码地址：`luban-h5/front-end/h5/src/engine-entry.js`
+- 打开的预览窗口`preview.vue`, 里面的预览部分对应的其实是一个 iframe
+- 该 iframe 对应的即一个H5页面，iframe.src 一般为：https://h5.luban-h5.com/works/preview/页面Id?view_mode=preview
+- 该H5最终是由后端的模板引擎(鲁班采用的是 ejs) 进行渲染：
+ 后端模板引擎渲染的基本原理，参见：[previewOne](https://github.com/ly525/luban-h5/blob/bd486ce16fc24bfd7030fc51857a579776e12e68/back-end/h5-api/api/work/controllers/Work.js#L12)，关键代码如下：
+  ```js
+  previewOne: async (ctx) => {
+    const work = await strapi.services.work.findOne(ctx.params);
+    return ctx.render('engine', { work });
+  },
+  ```
+
+### 后端
+#### 1. 快速上手
 ```bash
 # 默认当前目录为 luban 项目的根目录
 cd back-end/h5-api
@@ -137,58 +166,47 @@ yarn dev
 请继续阅读，进行相关配置
 ```
  
-### 2. 注意事项
-> 如何打开下图所示的页面呢？对于node 后端框架， 大家知道比较多的可能是 阿里的 egg.js、express.js、koa.js，鲁班H5采用的是 [strapi.js](strapi.io) 作为其后端框架，[答疑:为何采用Strapi.js作为后端?](https://github.com/ly525/luban-h5/discussions/234)
-
-> 我们在上一步`cd back-end/h5/api && yarn && yarn dev`之后，就可以打开 strapi.js 其自带的管理后台了（用来管理数据库Model、接口权限、注册用户、新增用户等），本地访问地址为：http://localhost:1337/admin
-
-> 请将右上角语言改为：zh-Hans(简体中文)，如果你是第一次访问：http://localhost:1337/admin ，那么你需要按照页面的提示进行注册下（和你正常注册淘宝一样，输入邮箱、用户名、密码、确认密码即可），这个注册只是本地注册，没有其它影响。注册完成之后，就可以使用刚才注册的账号、密码登录了
-
-1. 本地开发，如果后端接口报错 403 Forbidden，请按照下图的操作，打开接口的访问权限接口：`[Roles And Permission] -> [Public] - [Permissions]`
+### 管理后台
+> 本地访问地址为：[http://localhost:1337/admin](http://localhost:1337/admin)
+
+::: details 详细介绍
+- 对于 Node 框架，大家耳熟能详是 Egg.js、Express.js, Koa.js 这些
+- 鲁班H5采用的是 [Strapi.js(一个 CMS)](strapi.io) 作为其后端框架，[答疑:为何采用Strapi.js作为 鲁班H5的后端框架?](https://github.com/ly525/luban-h5/discussions/234)
+- 我们在上一步`cd back-end/h5/api && yarn && yarn dev`之后，就可以打开 [鲁班H5 的管理后台](http://localhost:1337/admin)了
+- 管理后台主要功能：
+  - 管理数据库Model
+  - 接口权限
+  - 用户注册、管理
+  - 上传素材管理
+  - 接口文档
+  - 等等
+
+- 步骤：
+  - 如果你是第一次访问：[http://localhost:1337/admin](http://localhost:1337/admin) ，按照页面提示注册即可
+  - 注册完成之后，使用刚才注册的账号、密码登录管理后台
+  - 在右上角可以修改语言：zh-Hans(简体中文)
+:::
+
+## 常见问题
+### 接口 `403 Forbidden`
+::: details 点击查看 403 解决方案
+- 本地开发，如果后端接口报错 403 Forbidden
+- 访问：[http://localhost:1337/admin](http://localhost:1337/admin) (鲁班的管理后台，在这里管理数据、接口相关权限)
+- 请按照下图的操作，打开接口访问权限：`Roles And Permission -> Public -> Permissions`
  
 ![1567438464273-e0892ee2-5dca-45ec-a528-8090d80b23bd](https://user-images.githubusercontent.com/12668546/65381949-32addd00-dd2e-11e9-967a-e313dc6fca89.png)
  
 ![1567438463824-d6b87f12-eecf-4ae2-aa9c-bb4c73c4127d](https://user-images.githubusercontent.com/12668546/65381950-32addd00-dd2e-11e9-859a-dbec0941dc5a.png)
  
-##### 上传封面图使用
+#### 上传封面图使用
 ![image](https://user-images.githubusercontent.com/12668546/91663261-64245080-eb1a-11ea-9e31-f43f910cbb57.png)
+:::
  
+### 预览页面显示空白
+> 解决方案看这里：[2. 构建预览所需的渲染引擎](#_2-构建预览所需的渲染引擎)
  
-
-## 前端环境搭建
-### 1. 快速上手
-
-```bash
-# 默认当前位置目录为 luban-h5 项目的根目录
-cd front-end/h5 && yarn && yarn build:engine && yarn dev
-
-# 更多命令请参见 project/front-end/h5/package.json
-```
-
-### 2. 构建预览所需的渲染引擎
-- 如果在`「1. 快速上手」` 已经执行了 `yarn build:engine`，这一步可以跳过
-- 关于此部分有疑惑，请直接到[社区](https://support.qq.com/products/93432/)评论即可
-
-1. 只需要在`front-end/h5`目录下，运行：`yarn build:engine` 即可
-2. 下面的内容感兴趣可以了解，感觉内容太多可以不看
-
-#### 2.1 基本原理
-作品预览的基本原理参见 [previewOne](https://github.com/ly525/luban-h5/blob/bd486ce16fc24bfd7030fc51857a579776e12e68/back-end/h5-api/api/work/controllers/Work.js#L12)，关键代码如下：
-
-```js
-previewOne: async (ctx) => {
-  const work = await strapi.services.work.findOne(ctx.params);
-  return ctx.render('engine', { work });
-},
-```
-
-#### 2.2 如何构建
-1. 在`front-end/h5`目录下，运行：`yarn build:engine`
-2. 构建完成之后，后端的`h5-api/public`里面会多一个文件夹 `engine-assets`
-3. 打开的预览窗口`preview.vue`, 里面的预览部分对应的其实是一个 iframe，可以看看对应的源码
-4. 这个预览其实依赖后端的模板引擎（比如 ejs、jade等）
-5. 参照这里`luban-h5/front-end/h5/vue.config.js`的`engineOutputDir` 变量（这个变量就是预览引擎构建完成，生成的文件所在的目录。默认是后端的 `back-end/h5-api/public/engine-assets` 目录）
-
+## 视频教程
+<iframe src="//player.bilibili.com/player.html?aid=76827615&cid=131403430&page=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" width="100%" height="600"> </iframe>
  
 ---
 > 欢迎大家到[鲁班H5-社区](https://support.qq.com/products/93432/) 交流，在这里可以提问、反馈意见和建议，与作者直接互动