---
title: 贡献指南
description: Shift2Modern 的贡献指南
---
# Contribution Guidelines
> 本内容可能会随着项目的发展而变更。请在撰写指南前先阅读 **最新版本** 的本指南。
参阅 [*Mintlify* 组件](https://mintlify.com/docs/components) 文档来了解可用组件。
## 文件结构
### 文本
所有需要维护的文本文件均位于 `content` 文件夹下。除首页外，指南页面统一位于 `content/guide/`。根目录中的 `index.mdx` 和 `guide/` 目录由脚本生成，仅供 Mintlify 本地预览和构建使用，请勿直接编辑。
```text
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 需要的根目录路径。可以手动运行：
```shell
pnpm run prepare:mintlify
```
### 图片
所有图片文件均位于 `public/img` 文件夹下，文件夹结构如下：
```text
public
├── img
│ ├── 0
│ │ ├── 0
│ │ │ ├── 1.png
│ │ │ └── 2.png
│ │ └── 1
│ │ ├── 1.png
│ │ └── 2.png
│ ├── 1
│ │ └── ...
│ ├── 2
│ │ └── ...
...
```
图片目录可按章节继续放在 `public/img` 下。引用图片时使用 `/img/...` 路径，不要写成 `public/img/...`。
图片推荐分辨率为 1920x1080 ，使用PNG格式。可使用 [Squoosh](https://squoosh.app/) 中的 *OxiPNG* 压缩，effort 为 2。
## 文档编写
### 行文准则
> - 正文使用**简体中文**，专有名词应保留**原文**或**注释说明**。
> - 注意主客体间的关系，尽量避免使用**第一人称**和**第二人称**。
> - 行文应遵循 **中立客观的原则**，仅对技术/产品进行描述，**不**涉及**任何特定** **政治**、**宗教** 或 **观念倾向** 的内容
### Front-matter
[Mintlify Frontmatter](https://mintlify.com/docs/pages)
所有文档均需要添加 *Front-matter*，*Front-matter* 用于指定文档的标题、描述、图标等信息。
*Front-matter* 例：
```markdown
---
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* 前换行两次。
- 章节间请添加一次换行。
- 代码框前后添加换行。
> 也可在单行末尾添加 `
` 换行来解决特殊位置的换行问题。（请注意 `
` 前需添加空格）
### 文本格式
`待完善`
> 文本撰写请先参照 [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-Hans.md)，但此篇中部分标点符号用法与标点符号用法并未遵守中国国家标准 [标点符号用法（GB/T 15834-2011）](https://openstd.samr.gov.cn/bzgk/gb/newGbInfo?hcno=22EA6D162E4110E752259661E1A0D0A8)，对于需要求证的用法，可以参阅由 教育部语言文字信息管理司 组编，语文出版社出版的《〈标点符号用法〉解读》（ISBN 9787802415591）。
本指南中对格式使用有如下特殊规范：
> - 对于软件名，特定称谓请使用斜体，例如 *Nuxt*、*Vue*、*Docus* 等。
> - 对文章/内容进行引用时，如需使用引号将目标内容包裹，请将引号至于链接之外。
> e.g. `“[S2M](https://shift2modern.dev/)”`。
### 代码块/代码框
[Mintlify Code Blocks](https://mintlify.com/docs/components/code-blocks)
代码片段使用代码块并加注 *语言* 表示：
\`\`\`shell
guide -sample
\`\`\`
参数、组合键等内容使用代码框 \`sample\`。
### 终端指令
终端指令使用 *Terminal* 组件：
[Docus doc](https://docus.dev/api/components#terminal)
```bash
nuxi build
```
```md [Code]
```bash
nuxi build
```
```
对于多种终端指令，可以使用 *Code Group* 组件：
[Docus doc](https://docus.dev/api/components#code-group)
```bash [Yarn]
yarn add docus
```
```bash [NPM]
npm install docus
```
```md [Code]
```bash [Yarn]
yarn add docus
```
```bash [NPM]
npm install docus
```
```