Skip to content

格式规范

Jump to bottom
炽翎 edited this page Jul 18, 2021 · 7 revisions

提交规范

可以查看 这次提交 的 commit message 作为示例，或参考 这个网站 了解提交信息的既定书写格式：

<type>(<scope>): <subject>
^-------------^  ^-------^
|                |
|                +-> 主题。总结 commit 内容，用现在时书写。
|
+-------> 目的: chore, docs, feat, fix, refactor, style, 或 test。<scope> 为可选项。

  hash: (对应到官方英文文档的某次更新 commit hash)
  time: (由 `new Date().toLocaleString()` 生成的时间戳)
  • 如果您贡献提交的目的并不是与官方英文文档同步内容相关，为 chore 或其他类型，body 部分可以省略。
  • 如果您的贡献无需提交后经由 CI 验证，需要加上 [ci skip] 标识符。

释义

  • feat: (新功能，面向用户)
  • fix: (bug 修复，面向用户)
  • docs: (编辑文档)
  • style: (格式，如全角半角；没有 production code 方面的改变)
  • refactor: (比如重命名变量)
  • test: (加入缺少的测试，没有 production code 方面的改变)
  • chore: (更新依赖等，没有 production code 方面的改变)

文档格式规范

译注写法

  1. 在原文需要加译者注的位置添加角标：
... <sup>[[1]](#footnote-1)</sup> ... <sup>[[2]](#footnote-2)</sup> ...
  1. 在文章最末尾加入译者注的内容，格式如下：
<small>
__译者注__
<a id="footnote-1"></a>[1] ...
<a id="footnote-2"></a>[2] ...
<a id="footnote-3"></a>[3] ...
</small>

标点符号

  • 逗号、句号、分号、冒号、叹号、问号，统一使用全角字符：，。；：！？
  • 破折号使用：——
  • 引号统一使用 “ ” 和 ‘ ’
  • 括号统一使用全角括号 （）
  • 非注释部分的代码除外，保留英文标点符号。

内联代码或代码关键字

  • 务必用反引号（即英文输入法下，按键盘上 Tab 键上方的那个键）将内容括起来。
  • 包括代码注释中出现代码或代码关键字时，也要括起来。

空格的使用

  • 英文单词和英文单词之间要有一个空格 something in English

  • 中文和英文单词之间要有一个空格 中文当中有 something 是英文

  • 英文单词和标点符号之间没有空格 这里是一句中文，something 又是英文

这时英文前无需

链接、斜体、粗体与行内代码等

对于 Markdown 中上述的行内简单样式，为了保证 Vitepress 中良好的渲染效果，我们提倡在文档中使用如下的格式：

<!-- 链接 -->
这是一个 [链接](https://github.com/vitejs/vite) 指向 Vite 官方仓库

<!-- 加粗 -->
这是一个 **加粗** 的文字

<!-- 斜体 -->
这是一个 _斜体_ 的文字 <!-- Good -->
这是一个 *斜体* 的文字 <!-- 不推荐，尽在下划线效果不可用时作为替代使用 -->

<!-- 行内代码 -->
这是一个 `code` 行内代码
假如后面就是标点符号 `code`：

你可能已经注意到，默认情况下，在两端我们都加上了空格。

这里的某些规则可能暂时和 Vue.js 中文文档的风格 不太一致，如果您曾参与过 Vue 中文文档可能与您的习惯不一，望周知。

这是为了保证文档视图中不会出现字符靠太近而黏合的问题。

关于文档中的链接，针对以下两种 Markdown 书写：

<!-- 链接前后带空格  -->
Vite 支持了一套 [通用插件 API](./api-plugin) 扩展了 Rollup 的插件接口

<!-- 链接前后不带空格 -->
Vite 支持了一套[通用插件 API](./api-plugin)扩展了 Rollup 的插件接口

Vitepress 和 Vuepress 中对以上两种写法的渲染视觉效果为：

链接前后带空格

image

链接前后不带空格

image

不带空格的形式 与 带空格相比，没有那么突出。

同样这类情况还包括 Markdown 中的斜体字：

这是一个_斜体_尝试 <!-- Vitepress 和 Vuepress 中无效！  -->

这是一个*斜体*尝试 <!-- 前后无空格 -->

这是一个 _斜体_ 尝试 <!-- 前后有空格 -->

下面是效果，不带空格的情况看上去中文字体的笔画之间会接在一起，变得很拥挤，观感较差。

image

Clone this wiki locally