​
Contribution Guidelines

本内容可能会随着项目的发展而变更。请在撰写指南前先阅读 最新版本 的本指南。

本指南使用 [*Mintlify*](https://mintlify.com/) 构建，页面使用 MDX 编写

参阅 Mintlify 组件 文档来了解可用组件。

​
文件结构

​
文本

所有需要维护的文本文件均位于 content 文件夹下。除首页外，指南页面统一位于 content/guide/。根目录中的 index.mdx 和 guide/ 目录由脚本生成，仅供 Mintlify 本地预览和构建使用，请勿直接编辑。 
content/
├── index.mdx                         # 首页
└── guide/
    ├── preface.mdx                   # 前言
    ├── contribution-guidelines.mdx   # 贡献指南
    ├── vscode/                       # VSCode
    ├── git/                          # Git
    ├── markdown/                     # Markdown
    ├── terminal/                     # Terminal
    ├── github/                       # GitHub、GitHub Desktop、速通协作
    ├── mindmap/                      # Mindmap
    └── regexp/                       # 正则表达式
页面顺序和公开路径由根目录的 docs.json 控制。新增页面后，需要同时把页面路径加入 docs.json 的 navigation.tabs[].groups[].pages。 在本地预览或构建前，脚本会把 content/ 中的源文件同步到 Mintlify 需要的根目录路径。可以手动运行： 
pnpm run prepare:mintlify

​
图片

所有图片文件均位于 public/img 文件夹下，文件夹结构如下： 
public
├── img
│   ├── 0
│   │   ├── 0
│   │   │   ├── 1.png
│   │   │   └── 2.png
│   │   └── 1
│   │       ├── 1.png
│   │       └── 2.png
│   ├── 1
│   │   └── ...
│   ├── 2
│   │   └── ...
...
图片目录可按章节继续放在 public/img 下。引用图片时使用 /img/... 路径，不要写成 public/img/...。 图片推荐分辨率为 1920x1080 ，使用PNG格式。可使用 Squoosh 中的 OxiPNG 压缩，effort 为 2。

​
文档编写

​
行文准则

  • 正文使用简体中文，专有名词应保留原文或注释说明。
  • 注意主客体间的关系，尽量避免使用第一人称和第二人称。
  • 行文应遵循 中立客观的原则，仅对技术/产品进行描述，不涉及任何特定 政治、宗教 或 观念倾向 的内容

​
Front-matter

Mintlify Frontmatter 所有文档均需要添加 Front-matter，Front-matter 用于指定文档的标题、描述、图标等信息。 Front-matter 例： 
---
title: Sample Guide 1
description: This is a sample guide.
---
Front-matter 必须包含 title 和 description，其 title 须和 Headline 1 相同。
如需隐藏目录栏（Table of Contents），可在 Front-matter 中添加 toc: false。

​
Headline 使用

Headline 1 即 # Sample 仅用与指南的标题。
其余依据章节划分自行判断，对于应在同位次的子章节烦请使用相同的 Headline。

​
换行

  • 每个 Headline 下换行一次，在下一个 Headline 前换行两次。
  • 章节间请添加一次换行。
  • 代码框前后添加换行。
也可在单行末尾添加 <br /> 换行来解决特殊位置的换行问题。（请注意 <br /> 前需添加空格）

​
文本格式

待完善
文本撰写请先参照 中文文案排版指北，但此篇中部分标点符号用法与标点符号用法并未遵守中国国家标准 标点符号用法（GB/T 15834-2011），对于需要求证的用法，可以参阅由 教育部语言文字信息管理司 组编，语文出版社出版的《〈标点符号用法〉解读》（ISBN 9787802415591）。
本指南中对格式使用有如下特殊规范：
  • 对于软件名，特定称谓请使用斜体，例如 Nuxt、Vue、Docus 等。
  • 对文章/内容进行引用时，如需使用引号将目标内容包裹，请将引号至于链接之外。
    e.g. “[S2M](https://shift2modern.dev/)”。

​
代码块/代码框

Mintlify Code Blocks 代码片段使用代码块并加注 语言 表示：

Sample

```shell
guide -sample
```
参数、组合键等内容使用代码框 `sample`。

​
终端指令

终端指令使用 Terminal 组件： Docus doc 
nuxi build
[Code]
```bash
nuxi build


对于多种终端指令，可以使用 *Code Group* 组件：

[Docus doc](https://docus.dev/api/components#code-group) <br />

```bash [Yarn]
    yarn add docus
[NPM]
npm install docus
[Code]

  ```bash [Yarn]
  yarn add docus
[NPM]
npm install docus