docs: update reference

Mereithhh · Feb 28, 2023 · c24503b · c24503b
1 parent 8922137
commit c24503b
Show file tree

Hide file tree

Showing 8 changed files with 207 additions and 241 deletions.
diff --git a/docs/ref/api.md b/docs/ref/api.md
@@ -5,21 +5,25 @@ icon: http
 
 目前还没写专门的 API 参考，但是可以用生成的 `swagger` 做为参考。其中 `public` 标签下的都是不需要鉴权的。
 
-可以在后台侧边栏中点击关于，然后点击关于界面的`API文档`来进入 API 文档页面：
+可以在后台侧边栏中点击关于，然后点击关于界面的 `API 文档` 来进入 API 文档页面：
 
 ![API 文档入口](https://pic.mereith.com/img/0b487fe87735562feff3825b040c5353.clipboard-2022-08-29.png)
 
 由于分离式的设计，你完全可以把本项目当作无头 CMS 来使用。只用本项目的后端和 server，自己写前端，或者自己写一个 `hexo` 的渲染器。
 
-（也许以后我会加上一些其他的渲染器支持，比如对接 `hexo` 和 `vue-press`）
+（也许以后我会加上一些其他的渲染器支持，比如对接 `hexo` 和 `vuepress`）
 
-> swagger 路径： /swagger
-> 参考： [https://blog-demo.mereith.com/swagger](https://blog-demo.mereith.com/swagger)
+::: note
 
-举个例子，你可以通过 GET /api/public/article/:id ，获取置顶文章的 JSON 内容。
+- swagger 路径： `/swagger`
+- 参考： [https://blog-demo.mereith.com/swagger](https://blog-demo.mereith.com/swagger)
+
+:::
+
+举个例子，你可以通过 `GET /api/public/article/:id` ，获取置顶文章的 JSON 内容。
 
 你可以点击这个链接看一下效果： [https://blog-demo.mereith.com/api/public/article/28](https://blog-demo.mereith.com/api/public/article/28)
 
 ## 关于鉴权的接口
 
-所有需要鉴权的接口是通过请求头中 `token` 字段鉴权的，可以复制登录后台后的请求头中的 `token` 来使用鉴权 api，有效期和登录过期时间相同，可通过后台中的高级设置调整过期时间。
+所有需要鉴权的接口是通过请求头中 `token` 字段鉴权的，可以复制登录后台后的请求头中的 `token` 来使用鉴权 API，有效期和登录过期时间相同，可通过后台中的高级设置调整过期时间。
diff --git a/docs/ref/baota.md b/docs/ref/baota.md
@@ -3,11 +3,11 @@ title: 通过宝塔面板部署
 icon: linux
 ---
 
-::: warn 温馨提示
+::: tip 温馨提示
 
 VanBlog 现在支持一键脚本部署了。经过测试，宝塔也可以通过一键脚本进行部署。
 
-建议您通过[一键脚本部署](/guide/docker.md#一键脚本部署)，这样后期可以通过脚本一键升级会方便一些。
+建议您通过[一键脚本部署](../guide/docker.md#一键脚本部署)，这样后期可以通过脚本一键升级会方便一些。
 
 如果您想通过图形化部署，请看下文。
 
@@ -87,7 +87,7 @@ services:
 
 等启动完毕后即可！
 
-和普通部署一样，浏览器打开 `http://<你的域名>:8880/admin/init` ，并按照提示初始化即可。具体设置项可以参考 [站点配置](/feature/basic/setting.md)
+和普通部署一样，浏览器打开 `http://<你的域名>:8880/admin/init` ，并按照提示初始化即可。具体设置项可以参考 [站点配置](../feature/basic/setting.md)。
 
 有问题的话可以查看一下容器的日志进行排查。
 
@@ -97,12 +97,12 @@ services:
 
 ![](https://pic.mereith.com/img/47a03229d46e9120ad1e7bf1abf4b504.clipboard-2022-09-14.png)
 
-如果你只部署 `VanBlog` ，并想关闭 `nginx` ，请输入以下命令关闭 `nginx`:
+如果你只部署 `VanBlog` ，并想关闭 Ngnix ，请输入以下命令关闭 Ngnix:
 
 ```bash
 nginx -s stop
 ```
 
 ## 反代
 
-请移步 [反代](/guide/nginx.md)
+请移步 [反代](../guide/nginx.md)。
diff --git a/docs/ref/changelog.md b/docs/ref/changelog.md
diff --git a/docs/ref/dev.md b/docs/ref/dev.md
@@ -3,14 +3,17 @@ title: 开发指南
 icon: vscode
 ---
 
-:::info 提示
-本项目处于初始阶段，如有 bug 请多担待。
+::: info 提示
+
+本项目处于早期开发阶段 (Early WIP)，如有 bug 请多担待。
+
 :::
+
 本项目使用了 `JavaScript` 和 `TypeScript` 实现。
 
 如果你想参与 `VanBlog` 开发，可以进群哦：
 
-- [VanBlog  开发群](https://jq.qq.com/?_wv=1027&k=mf2CguM8)
+- [VanBlog 开发群](https://jq.qq.com/?_wv=1027&k=mf2CguM8)
 
 ## 路径结构
 
@@ -23,10 +26,10 @@ icon: vscode
 ├── LICENSE # 开源协议
 ├── package.json
 ├── packages # 代码主体
- |  ├── admin # 后台前端代码
- |  ├── server # 后端代码
- |  ├── waline # 内嵌 waline 评论系统
- |  └── website # 前台前端代码
+|  ├── admin # 后台前端代码
+|  ├── server # 后端代码
+|  ├── waline # 内嵌 waline 评论系统
+|  └── website # 前台前端代码
 ├── README.md
 └── yarn.lock
 ```
@@ -35,24 +38,19 @@ icon: vscode
 
 只列出大体上框架级别的，一些细节就直接看代码吧。
 
-前台： [next.js](https://nextjs.org/)、[react.js](https://reactjs.org/)、[tailwind-css](https://tailwindcss.com/)
-
-后台： [ant design pro](https://pro.ant.design/zh-CN/)、[ant design](https://ant.design/)
-
-后端： [nest.js](https://nestjs.com/)、[mongoDB](https://www.mongodb.com/)
-
-CI： [docker](https://www.docker.com/)、[nginx](https://www.nginx.com/)、[github-actions](https://docs.github.com/cn/actions)
-
-文档： [vue-press](https://vuepress.vuejs.org/)、[vue-press-hope](https://vuepress-theme-hope.github.io/)
+- 前台： [next.js](https://nextjs.org/)、[react.js](https://reactjs.org/)、[tailwind-css](https://tailwindcss.com/)
+- 后台： [ant design pro](https://pro.ant.design/zh-CN/)、[ant design](https://ant.design/)
+- 后端： [nest.js](https://nestjs.com/)、[mongoDB](https://www.mongodb.com/)
+- CI： [docker](https://www.docker.com/)、[nginx](https://www.nginx.com/)、[github-actions](https://docs.github.com/cn/actions)
+- 文档： [vuepress](https://vuejs.press/zh/)、[vuepress-theme-hope](https://theme-hope.vuejs.press/zh/)
 
 ## 数据库
 
 开发之前，要有一个 `mongodb` 数据库才行。推荐用 `docker` 起一个。
 
 ## 一键开发命令
 
-为了方便（懒），增加了一键开发命令：
-在配置好后端开发的 `yaml` 配置文件后，先安装依赖：
+为了方便（懒），增加了一键开发命令。在配置好后端开发的 `yaml` 配置文件后，先安装依赖：
 
 ```bash
 cd packages/server && yarn && cd ..
@@ -87,7 +85,7 @@ yarn dev
 
 ## 后台开发
 
-采用 `ant deign pro`
+使用 `ant deign pro`
 
 ```bash
 cd packages/admin
@@ -101,7 +99,7 @@ yarn start
 
 ## 后端开发
 
-采用 `nestjs` 框架构建。
+使用 `nestjs` 框架构建。
 
 ```bash
 cd packages/server
@@ -115,7 +113,7 @@ yarn start:dev
 
 默认的数据库是本地的 `mongo`，如果你需要修改，可以在本目录（`packages/server`）下新建`config.yaml`：
 
-```
+```yml
 database:
   url: mongodb://somemongo:27017/vanBlog?authSource=admin
 # 配置静态图床的文件夹
@@ -124,7 +122,6 @@ static:
 waline:
   db: walineDev
 log: /code/github/van-blog/log
-
 ```
 
 ## 文档开发
@@ -137,7 +134,7 @@ yarn docs:dev
 
 ## 镜像构建
 
-根目录直接打包就行。
+直接打包根目录即可。
 
 ### act
 
@@ -163,7 +160,7 @@ docker build --build-arg VAN_BLOG_BUILD_SERVER=$VAN_BLOG_BUILD_SERVER -t mereith
 
 另外有一键脚本可以在发版之后自动拷贝 changelog 并发布：
 
-```
+```bash
 yarn release-doc
 ```
 

diff --git a/docs/ref/dsm.md b/docs/ref/dsm.md
@@ -11,23 +11,23 @@ icon: router
 
 在 `Docker` 套件中点击 `映像/新增/从 URL 添加`:
 
-![](https://pic.mereith.com/img/37e817403c5f6b3877780b41f99ea2e0.clipboard-2022-08-29.png)
+![添加](https://pic.mereith.com/img/37e817403c5f6b3877780b41f99ea2e0.clipboard-2022-08-29.png)
 
 填入地址为 `mereith/van-blog`：
 
-![](https://pic.mereith.com/img/428cef523d23e2a5d2b19fcb59fb2bf0.clipboard-2022-08-29.png)
+![填写地址](https://pic.mereith.com/img/428cef523d23e2a5d2b19fcb59fb2bf0.clipboard-2022-08-29.png)
 
 标签选择默认的 `latest` 即可：
 
-![](https://pic.mereith.com/img/409c41cbe5ebf9d3be1630965b5a6e46.clipboard-2022-08-29.png)
+![选择标签](https://pic.mereith.com/img/409c41cbe5ebf9d3be1630965b5a6e46.clipboard-2022-08-29.png)
 
 仿照上面的增加 `mongo` 镜像，版本选择 `4.4.9` 的，如图所示（有些机器不支持 AVX，用最新的会报错）：
 
-![](https://pic.mereith.com/img/acd15a0e47c3a28d78a78c9102a7593e.clipboard-2022-09-15.png)
+![添加 mongo 镜像](https://pic.mereith.com/img/acd15a0e47c3a28d78a78c9102a7593e.clipboard-2022-09-15.png)
 
 完成后如图：
 
-![](https://pic.mereith.com/img/94080b16a8305acbd1552ca3b31596bb.clipboard-2022-09-15.png)
+![添加结果](https://pic.mereith.com/img/94080b16a8305acbd1552ca3b31596bb.clipboard-2022-09-15.png)
 
 ### 创建容器
 
@@ -48,21 +48,25 @@ icon: router
 
 完成后启动即可。
 
-### 创建 vanblog 容器
+### 创建 VanBlog 容器
 
 和上面一样，点击 `容器/新建` ，选中刚刚下载的 `mereith/van-blog:latest` 镜像，容器名称为 `vanblog`。
 
 ![image.png](https://pic.mereith.com/img/6b237de9e368fbcda040c5eaa5aec363.image.png)
 
 ### 环境变量
 
-点击`高级设置/环境`，其他的都可忽略，但下表的环境变量需要设置/新加：
+点击 `高级设置/环境`，其他的都可忽略，但下表的环境变量需要设置/新加：
 
 | 名称  | 值           |
 | ----- | ------------ |
 | EMAIL | 你自己的邮箱 |
 
-> 参考: [vanblog 文档/环境变量配置](/ref/env.md) 中所示设置好环境变量。
+::: info 参考
+
+- 在 [VanBlog 文档/环境变量配置](./env.md) 中所示设置好环境变量。
+
+:::
 
 ### 链接
 
@@ -72,30 +76,30 @@ icon: router
 
 ### 端口映射
 
-然后点击下一步，进行端口映射，群晖不能用默认的 80 端口，所以可以映射成其他端口，比如 8880
+然后点击下一步，进行端口映射，群晖不能用默认的 `80` 端口，所以可以映射成其他端口，比如 `8880`。
 
 ![image.png](https://pic.mereith.com/img/5e6a5d6f07af5455b8fd4f06763cf858.image.png)
 
 ### 存储空间映射
 
-可以参考 [vanblog 文档/环境变量配置](/ref/env.md) 中的目录映射部分进行映射。
+可以参考 [VanBlog 文档/环境变量配置](./env.md) 中的目录映射部分进行映射。
 
 其中图床数据的目录映射推荐做一下，不然重置后可能会让你的博客本地图床图片都失效。
 
-| 容器内目录               | 说明                                                        |
-| ------------------------ | ----------------------------------------------------------- |
-| /app/static              | 图床中数据的存放路径，使用内置图床请务必映射好！            |
-| /var/log                 | 日志的存放路径，包括 access 日志、 Caddy 日志和前台服务日志 |
-| /root/.config/caddy      | caddy 配置存储路径                                          |
-| /root/.local/share/caddy | caddy 证书存储路径                                          |
+| 容器内目录                 | 说明                                                        |
+| -------------------------- | ----------------------------------------------------------- |
+| `/app/static`              | 图床中数据的存放路径，使用内置图床请务必映射好！            |
+| `/var/log`                 | 日志的存放路径，包括 access 日志、 Caddy 日志和前台服务日志 |
+| `/root/.config/caddy`      | caddy 配置存储路径                                          |
+| `/root/.local/share/caddy` | caddy 证书存储路径                                          |
 
 ### 完成
 
 然后点击完成即可：
 
 ![image.png](https://pic.mereith.com/img/1e75d553be53f7cea173177035f23cd9.image.png)
 
-### 排错
+### 错误排查
 
 如果发生错误，可以在容器日志中查看报错原因。
 
@@ -105,4 +109,8 @@ icon: router
 
 但如果你想在公网访问，我的建议是配置好反代后用最终使用的 URL 来访问进行初始化，否则内置图床上传的图片链接可能会有问题。
 
-> [FAQ](/ref/faq.md)
+::: info FAQ
+
+- [FAQ](./faq.md)
+
+:::
diff --git a/docs/ref/env.md b/docs/ref/env.md
@@ -3,33 +3,34 @@ title: 启动配置
 icon: async
 ---
 
-起容器时可以传递一系列的`环境变量`，修改后需要重启容器生效，具体含义如下：
+启动容器时可以传递一系列的 `环境变量`，修改后需要重启容器生效，具体含义如下：
 
 ## 环境变量
 
-::: info 警示  
-为避免特殊字符对 bash 的干扰，请务必将环境变量的值用双引号围起来!  
+::: warning 警示
+
+为避免特殊字符对 bash 的干扰，请务必将环境变量的值用双引号围起来!
 
 如 `"https://example.com"`
 
 :::
 
-| 名称                  | 必填 | 说明                                                                        | 默认值                                           |
-| --------------------- | ---- | --------------------------------------------------------------------------- | ------------------------------------------------ |
-| VAN_BLOG_DATABASE_URL | 否   | mongoDB URL                                                                 | `mongodb://mongo:27017/vanBlog?authSource=admin` |
-| VAN_BLOG_CDN_URL      | 否   | CDN 部署的 url，在开启之前请不要设置此项。此项会导致公共资源从此 URL 获取。 | `""`                                             |
-| VAN_BLOG_WALINE_DB    | 否   | 内嵌评论系统的 db 名，默认为 waline                                         | `""`                                             |
-| EMAIL                 | 否   | 用于自动申请 https 证书的邮箱                                               | `""`                                             |
+| 名称                    | 必填 | 说明                                                                        | 默认值                                           |
+| ----------------------- | ---- | --------------------------------------------------------------------------- | ------------------------------------------------ |
+| `VAN_BLOG_DATABASE_URL` | 否   | mongoDB URL                                                                 | `mongodb://mongo:27017/vanBlog?authSource=admin` |
+| `VAN_BLOG_CDN_URL`      | 否   | CDN 部署的地址，在开启之前请不要设置此项。此项会导致公共资源从此 URL 获取。 | `""`                                             |
+| `VAN_BLOG_WALINE_DB`    | 否   | 内嵌评论系统的数据库名，默认为 waline                                       | `""`                                             |
+| `EMAIL`                 | 否   | 用于自动申请 https 证书的邮箱                                               | `""`                                             |
 
 ## 目录映射
 
-| 容器内目录               | 说明                                                        |
-| ------------------------ | ----------------------------------------------------------- |
-| /app/static              | 图床中数据的存放路径，使用内置图床请务必映射好！            |
-| /var/log                 | 日志的存放路径，包括 access 日志、 Caddy 日志和前台服务日志 |
-| /root/.config/caddy      | caddy 配置存储路径                                          |
-| /root/.local/share/caddy | caddy 证书存储路径                                          |
+| 容器内目录                 | 说明                                                        |
+| -------------------------- | ----------------------------------------------------------- |
+| `/app/static`              | 图床中数据的存放路径，使用内置图床请务必映射好！            |
+| `/var/log`                 | 日志的存放路径，包括 access 日志、 Caddy 日志和前台服务日志 |
+| `/root/.config/caddy`      | caddy 配置存储路径                                          |
+| `/root/.local/share/caddy` | caddy 证书存储路径                                          |
 
 ## 站点配置
 
-请参考 ：[站点配置](/feature/basic/setting.md)
+请参考：[站点配置](../feature/basic/setting.md)