文档编写

文档使用 VitePress 生成的，只需要简单编写 Markdown 文件即可。

更加具体的使用，可以查看其文档。

URL

这部分说的是 markdwon 路径被渲染后的浏览器链接是什么。 例如：

• docs/server/a.md -> /xxx/server/a.html
• docs/server/index.md -> /xxx/server/index.html 或 /xxx/server/

其中，xxx 为 docs/.vuepress/config.mts 中配置的 base。

导航栏、侧边栏

加入了相应的 markdown 后，一般需要添加相应的导航，以便他人可以从主页（或其他页面）“点”进来，而不是硬生生地在浏览器输入 URL。

主要有导航栏和侧边栏两种配置，两种区别如下所示：

导航栏（navbar）在 docs/navbar.md 进行配置即可。

侧边栏（sidebar）在 sidebar.md 配置即可。 因为在 .vitepress/config.mts 配置了扫描 sidebar.md 的脚本，docs 目录下的所有 sidebar.md 都会生成相应的侧边栏。

两者都使用 markdown 列表 + 链接语法即可。 注意，缩进必须使用 2 个空格。

规范

1. 所有 markdown 文件名都是 index.md，例如你现在想建一个关于云服务器的说明，其归属 server 目录，那么文件的结构目录应该如下

docs/
├── server/
│   ├── cloud/
│   │   ├── index.md
│   │   └── img/
│   │       └── pic.png
│   ├── index.md
│   ├── other-server/
│   └── sidebar.md
└── navbar.md

其中

• docs/server/cloud/index.md：放置云服务器的说明
• docs/server/cloud/img/：这个目录放置云服务器说明需要用到的图片
• docs/server/sidebar.md：表示 server 这个目录的侧边栏

2. navbar.md、sidebar.md 以及 markdown 的图片等有关于本地资源的链接都使用相对地址，必须以 ./ 开头。navbar.md、sidebar.md 的链接无需写 index.md 或 index.html，例如上面的 docs/server/sidebar.md 可以配置为

- [服务器首页](./)
- [云服务器](./cloud/)
- [其他服务器](./other-server/)

说明：

• ./ 表示 docs/server/index.md
• ./cloud/ 表示 docs/server/cloud/index.md
• ./other-server/ 表示 docs/server/other-server/index.md

注意：链接最后的 / 不能省略。

压缩

由于目前文档采用 Github 仓库存放，图片等资源建议先通过压缩再 add 和 commit。 图片的压缩可以采用 TinyPng 这种在线压缩。