贡献指南

大写字母的关键字遵循 RFC-2119 中指定的含义。

问题

虽然不太可能，但在提交自己的问题之前，请先搜索现有的问题，并查找是否存在类似的问题。

拉取请求

请尝试将相关的更改分组到单个拉取请求中，并在必要时创建额外的请求。这将使审查和合并变得更加容易和快捷。

标记样式指南

该项目使用 Markdown 作为其标记语言。

该项目中并非所有文件都遵循这些指南，因为我们在编写完大部分指南后才制定了这些指南。如果您发现任何样式不一致，请提交报告或发送拉取请求以修复它们。

当更改文件以使用语义换行符时，请在单独的提交中应用此更改，并且不要在同一提交中执行任何其他内容更改。

Markdown 解析器

标记解析器是 markdown-it，它可以通过插件扩展，并且还附带了一些 Vitepress 的自定义扩展。您可以在 docs/.vitepress/config.ts 中的 markdown 选项中找到我们使用的插件列表。

行宽

行长度不得超过 80 个字符，表格、URL 和代码块除外。

使用 语义换行符 拆分文本。使用这些换行符，您几乎永远不会在一行上接近 80 个字符。即使您确实接近，您也应该能够轻松地在合适的位置添加换行符。此文件可以作为示例。

空白

块应该缩进 2 个空格，但首选视觉缩进。内联代码应使用代码围栏，尤其是在需要语法高亮时。

示例

- This sentence can be split
  using a semantic linefeed,
  as mentioned earlier.

1. The very same thing applies to this line,
   but it uses a three-spaces indent instead.

1.  You could also indent this block
    by 4 spaces.

应该避免尾随空格。使用 <br> 标签插入手动换行符，而不是使用两个尾随空格。

标题必须以两个空行开头，除非它们直接跟随另一个标题或文件的开头。

枚举和代码块应该用空行包围。

枚举

枚举列表必须与其周围文本位于相同的缩进级别。

• 无序列表应该使用以下层次结构

  - first level
    * second level

• 有序列表应该尽可能使用 1. 作为所有项目的编号

  1. This is the first item,
     but it may change places
     in the future.
  1. By always using ``1.``,
     we can swap lines around
     without worrying about numbering.

超链接

超链接不应该内联，而是使用延迟定义。链接文本不应该为“这里”。相反，描述目标页面涵盖的内容、表示的内容或可以概括的内容，并将引用添加到描述性文本中。如果链接文本本身不言自明，请使用描述性的简写。

超链接定义可以放在段落之后、部分末尾或文档末尾，无论哪种方式看起来更合适。

示例

This is some normal text.
Information on "text"
can be found [on Wikipedia][wiki-text].
<!-- and not "here" -->

[wiki-text]: https://en.wikipedia.org/wiki/Text

对于相对链接，请遵循 Vitepress 的建议，使用其 ` .md` 扩展名引用文件。在指南和参考部分之间链接时，请使用绝对路径。如果相对 URL 很短，您可以直接在文本中指定目标 URL。

标题

页面的标题在 YAML 前置 matter 中指定，并插入到渲染后的页面中作为一级标题。文件中的任何后续标题 **不得** 为二级标题或更低级别标题（其中更低级别指的是重要性，而不是数字值）。

每个标题 **应该** 在比它高一级别的标题下。

因此，第一个 Markdown 标题为 以下标题样式 **必须** 按显示顺序使用，出于技术原因（例如，h3 必须在 h2 或更高级别之后，**而不是** 在 h1 之后）。

示例

---
title: This will be heading 1
---

## Heading 2

### Heading 3

With text


### And proper spacing

## New Heading 2

### This SHOULD NOT be a h4

文件路径

文件路径（相对或绝对）**必须** 这样指定

`Packages/SomePackage/somefile.ext`

所有路径**必须** 使用正斜杠编写，除非它们是在 Windows 中使用。

文件扩展名（当引用文件类型时）**必须** 这样编写

`.ext`

快捷键

所有键绑定**应该** 使用我们自定义的 Key 组件编写。`k` 属性中的 Key 和弦使用与 Sublime Text 键映射相同的格式。您可以使用 `command` 和 `option` 用于 macOS 特定的绑定。

<Key k="ctrl+t" /> <!-- single-chord -->
<Key k="ctrl+k, ctrl+k" /> <!-- multi-choord binding  -->
<Key k="option+command+up" /> <!-- uses macOS-specific modifiers -->

除非另有说明，所有键绑定**必须** 引用 Windows 的默认设置。

Sublime Text 特定

• 命令面板中的命令标题**必须** 如下编写

  **Preferences: Settings - User**

• 菜单项标题（默认情况下来自主菜单）**必须** 如下编写（注意 `→`）

  *Preferences → Package Settings → ...*

注释

以下注释“关键字”可以在注释的开头使用，以标记要审查的部分

• XXX
• TODO

示例

<!-- TODO add some screenshots -->