文档编写规范

IMPORTANT

阅读本文档前，请确保你掌握了 Markdown 官方标准语法，可前往 Markdown语法教程进行学习。

文档规范

文档命名

所有文档的命名方式为：x.x-文档名

其中 x.x 在它的目录下必须是唯一的，不允许重复。

例如manual和develop都可以有一篇1.1，但manual不可以有两篇1.1

x.x 拥有排序功能。

例如文档的顺序是：0.0，0.1，1.1，1.2，2.1……

x.x 中的两个x分别对应父模块和子模块

例如manual中的1.x，对应的是第一章新手入门/快速开始相关的文档
例如develop中的2.x，对应的是文档站开发相关文档

标题规范

文档应当有且仅有一个一号标题，为本文档的主标题。
主标题的图标可访问REMIX ICON，复制对应的i标签代码在一号标题前例如：
html
```
<i class="ri-rocket-line"></i>
```
注意：要复制font标签代码，而不是直接改双引号内的名字！
文档的标题请勿带x.x，例如文件名叫1.1-快速开始.md的文档，标题应该为一号标题的快速开始
只有二号、三号标题会识别为快捷目录，其余标题均不会被识别。

NOTE

文档中若是使用了HTML代码，请在文档站本地测试确认样式无误后再提交，Markdown编辑器和文档站的预览会有所差异，以文档站的显示为准。

图片引用

为了向文档中添加图片，我们需要进行以下步骤

上传图片至公共仓库
- 将图片放在对应子目录中，例如docs/public/images/doc_image/
- 图片名称应当清晰描述其内容，使用中文、小写字母、连写符(-)、下划线(_)等等。
NOTE
doc_image：存放开发文档中的图片，用x-x表示对应开发文档的序号。如：/images/doc_image/0-0文件夹即表示存放开发文档0.0-MaaLYSK零基础开发指南.md中的图片
tutorial_image：存放用户手册中的图片。
构建图片的URL地址
- 公式：/images/子目录/文件名
- 例如：有一张图片上传到了public/images/docs_image/图片名.png，URL地址为/image/docs_image/图片名.png
在文档中插入图片
markdown
```
![图片说明](/image/doc_image/图片名.png)
```
也可以使用html语法插入图片（用此方法调整图片大小）
sh
```
<img src="/image/doc_image/图片名.png" alt="图片名" width="40%" title="图片名" />
```
图片居中的指令
sh
```
<div align="center">
  <img src="/image/tutorial_image/advanced/xx.png" alt="xx" width="xx%" />
</div>
```
- src 指定图片路径（可为相对或绝对 URL）。
- alt 在图片无法显示时提供文字说明，有助于无障碍访问。
- width/height 指定图片大小，可以为数字或者百分比。
- title 鼠标悬停时显示提示信息。

文档站相关

获取源码

项目地址：MaaLYSK

将项目Fork并Clone保存到本地后，使用编辑器打开（推荐VsCode）

项目结构

文档站的核心目录是/docs，开发和更新都只需要在这个目录中。文档站所需静态图片统一放在/docs/public/image下，并按文档类型与章节分目录管理。

  docs
  ├─ .vitepress                        # VitePress 配置
  │  ├─ theme/                         # 主题与组件
  │  │  ├─ components/                 # 自定义组件
  │  │  ├─ custom.css                  # 自定义样式
  │  │  └─ index.ts                    # 主题入口
  │  ├─ cache/                         # 本地缓存（自动生成）
  │  ├─ dist/                          # 编译产物（自动生成）
  │  └─ config.mts                     # 站点配置
  │
  ├─ en_us/                            # 英文文档
  │  ├─ develop/                       # 英文-开发文档（预留）
  │  ├─ manual/                        # 英文-使用手册
  │  └─ index.md                       # 英文首页
  │
  ├─ zh_cn/                            # 中文文档
  │  ├─ develop/                       # 中文-开发文档
  │  ├─ manual/                        # 中文-用户手册
  │  └─ index.md                       # 中文首页
  │
  ├─ public/                           # 静态资源
  │  ├─ image/                         # 文档图片资源
  │  │  ├─ doc_image/                  # 开发文档图片
  │  │  │  ├─ 0-0/                     # 开发文档章节配图
  │  │  └─ tutorial_image/             # 用户手册图片
  │  │     ├─ win/                     # Windows 图文教程
  │  │     ├─ mac/                     # macOS 图文教程
  │  │     ├─ Q&A/                     # 常见问题配图
  │  │     └─ update/                  # 更新说明配图
  │  ├─ logo.ico                       # 网站图标
  │  ├─ logo.png                       # 网站 Logo
  │  └─ apple-touch-icon.png           # 移动端图标
  │
  ├─ .markdownlint.yaml                # Markdown 检查配置
  └─ index.md                          # 根首页（入口）

环境安装

安装Node.JS

点击前往下载=>Node.JS，版本请确保 >18。

如何确认Node.JS安装成功：
打开终端（Windows用户可按Win+R，输入cmd后回车）
在终端中输入node -v后回车，出现版本号即代表安装成功

安装VitePress

在 MaaLYSK 项目根目录下终端执行（以npm为例）

shell

npm add -D vitepress@next

本地运行

在终端中执行以下命令后，在浏览器中打开本地网址，通常为http://localhost:5173/
shell
```
npm run docs:dev
```

手机端访问：保证电脑和手机在同一局域网（wifi）下

npm run docs:dev -- --host 0.0.0.0 --port 5173    #局域网访问

会出现一个network地址，如下，即可在手机查看访问

➜  Local:   http://localhost:5173/
➜  Network: http://192.168.5.31:5173/            #每个人地址不一样

打包编译

如果你想确认你的项目是否能成功编译并渲染，可以在终端中执行

shell

npx vitepress dev docs

更详细的相关文档可访问：VitePress：快速开始

提交代码

每次PR代码前，请确保你能在本地顺利执行打包编译再提交你的代码。

文档编写规范 ​

文档规范 ​

文档命名 ​

标题规范 ​

图片引用 ​

文档站相关 ​

获取源码 ​

项目结构 ​

环境安装 ​

安装Node.JS ​

安装VitePress ​

本地运行 ​

打包编译 ​

提交代码 ​