修改贡献指南

src/contributing/build.md

@@ -1,6 +1,5 @@
 ---
 title: 构建指南
-order: 3
 icon: build
 date: 2023-07-21 11:08:04
 updated: 2023-07-21 17:20:22

src/contributing/contributing.md

@@ -1,7 +1,6 @@
 ---
 title: 贡献指南
 icon: build
-order: 1
 date: 2023-07-20 23:05:53
 updated: 2023-07-21 11:56:02
 ---

src/contributing/markdown-demo.md

@@ -1,7 +1,6 @@
 ---
 title: Markdown 示例
 icon: markdown
-order: 2.1
 date: 2023-07-21 17:57:47
 updated: 2023-07-21 18:15:30
 ---

src/contributing/markdown.md

@@ -1,22 +1,26 @@
 ---
-title: Markdown
+title: 文档写作规范
 icon: markdown
-order: 2
 date: 2023-07-20 23:46:54
 updated: 2023-07-21 18:39:41
 ---
 
-# Markdown
+# 文档写作规范
 
-## Markdown 介绍
+## 文件命名
 
-如果你是一个新手，还不会编写 Markdown，请先阅读 [Markdown 介绍](https://theme-hope.vuejs.press/zh/cookbook/markdown/) 。
+文档网站根据每个 Markdown 源文件的路径确定每个页面的路由。因而，确定文件名时应慎重，一旦确定，尽量不要再改动。
+由于 Windows 不区分文件名大小写，故而 `option-B.md` 和 `option-b.md` 在 Windows 下会出现冲突。
 
-本文档中，Markdown 文件分为两种，一种是普通的撰写内容的 Markdown 文件，就比如本文件；另一种是每个目录下的 `README.md`，它们没有内容，仅为每个目录配置这个目录的名称。与其他 md 文件类似，二者均由 Frontmatter 和内容主体组成。
+我们使用的文件的命名规则是：
 
-## Markdown 配置
+- 文件名一律采用小写字母
+- 文件名应尽量使用单词全称，避免使用各种形式的简写
+- 若文件名中含多个单词，应使用连字符 (hyphen) `-` 连接
 
-VuePress 通过 Frontmatter 为每个 Markdown 页面引入配置。
+## 文档 frontmatter 规范
+
+通过 Frontmatter 为每个 Markdown 页面引入配置。
 
 Frontmatter 必须在 Markdown 文件的顶部，并且被包裹在一对三短划线中间。下面是一个基本的示例:
 
@@ -30,24 +34,269 @@ title: 页面的标题
 ...
 ```
 
-### 通用的 Frontmatter 键
+下面是一些常用得 frontmatter 键：
 
 | 键         | 类型   | 必填 | 默认值         | 描述                                                                                                             |
 | ---------- | ------ | ---- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
 | title      | string | 否   | 第一个一级标题 | 页面的标题。如果你不在 Frontmatter 中设置 title ，那么页面中第一个一级标题（即 # title）的内容会被当作标题使用。 |
 | shortTitle | string | 否   | 标题           | 当前页面的短标题，会在导航栏、侧边栏和路径导航中作为首选。                                                       |
 
-更多可以参考：[信息 Frontmatter 配置 | vuepress-theme-hope (vuejs.press)](https://theme-hope.vuejs.press/zh/config/frontmatter/info.html)
+[信息 Frontmatter 配置 | vuepress-theme-hope (vuejs.press)](https://theme-hope.vuejs.press/zh/config/frontmatter/info.html)
+[布局 Frontmatter 配置 | vuepress-theme-hope (vuejs.press)](https://theme-hope.vuejs.press/zh/config/frontmatter/layout.html#dir)
 
-### 对于每个目录下的 `README.md`
+## 文档语法风格
 
-| 键    | 类型    | 必填 | 默认值 | 描述                                                                                                             |
-| ----- | ------- | ---- | ------ | ---------------------------------------------------------------------------------------------------------------- |
-| title | string  | 否   |        | 页面的标题。如果你不在 Frontmatter 中设置 title ，那么页面中第一个一级标题（即 # title）的内容会被当作标题使用。 |
-| index | boolean | 否   | true   | 是否在侧边栏中索引当前页面。                                                                                     |
+所有教程均采用 Markdown  语言编写，下面列出了一些本文档中可能用到的语法和注意事项。
 
-更多可以参考：[布局 Frontmatter 配置 | vuepress-theme-hope (vuejs.press)](https://theme-hope.vuejs.press/zh/config/frontmatter/layout.html#dir)
+查看 [Markdown 语法预览](markdown-demo.md)
 
-## Markdown 内容语法
+### 标题
 
-查看 [Markdown 语法预览](markdown-demo.md)
+```md
+# 一级标题
+## 二级标题
+### 三级标题
+#### 四级标题
+```
+
+::: tip
+
+一级标题是文档名，对应页面标题。一篇文档应有且只有一个一级标题
+
+:::
+
+- 文档内容从二级标题开始。
+- 文档中标题级别应逐级递增，例如：二级标题内应跟随三级标题，而不能越过三级标题直接使用四级标题
+- 标题不应含有特殊字符：如 latex 公式，代码块，数字编号等，不应以标点符号结尾
+- 标题前后空一行。
+
+### 正文文本
+
+```md
+正文段落 1
+(空行)
+正文段落 2
+```
+
+::: tip
+
+- 中文字符与英文字符和数字之间应加上空格，如 `中文 ABC 中文` 而非 `中文ABC中文`
+   `中文 123 中文` 而非 `中文123中文`
+- 标点符号采用全角，如 `，`、`。`、`：`、`、`、`？` 等
+   标点符号与中文字符、英文字符以及数字之间不需加空格
+- 大小写应正确，如：`Zotero` 不是 `zotero`，`GitHub` 不是 `github`
+- 正文中部分专有词和特殊符号，可以放入 `行内代码` 来表示，美观且不容易发生错误，例如：
+   操作步骤：`编辑` - `首选项` - `引用` 。
+
+:::
+
+### 文字样式
+
+```md
+这是一段文本，**用两对星号包裹的内容会被加粗**，而*只用一对星号包裹的内容会显示为斜体*，用~~两对波浪线包裹的内容会显示为删除~~。
+```
+
+预览：
+这是一段文本，**用两对星号包裹的内容会被加粗**，而*只用一对星号包裹的内容会显示为斜体*，用~~两对波浪线包裹的内容会显示为删除~~。
+
+### 无序列表和有序列表
+
+```md
+#### 无序列表
+
+- item 1
+  - 更多的列表项
+  - 更多的列表项
+  - 更多的列表项
+- item 2
+- item 3
+
+#### 有序列表
+
+1. item 1
+2. item 2
+3. item 3
+```
+
+### 链接
+
+```md
+[相对路径访问主页](../README.md)
+
+[相对路径访问贡献指南](./contributing.md)
+```
+
+### 图片
+
+```md
+![Logo](../.vuepress/public/assets/icon/chrome-192.png)
+```
+
+::: tip
+
+所有的图片资源都应放入 `src/assets` 内，尽量以通俗的方式描述图片内容。
+
+:::
+
+### 视频
+
+```md
+一个 B 站视频:
+
+<BiliBili bvid="BV1kt411o7C3" />
+
+一个自定义空降地址的 B 站视频:
+
+<BiliBili aid="34304064" cid="109293122" ratio="9:16" time="60" page="2" />
+```
+
+::: tip
+
+受限于存储空间，文档不支持插入本地视频，引入视频请上传 bilibili，然后以以上语法引入视频。
+
+:::
+
+### 表格
+
+使用 GitHub 风格表格：
+
+```md
+|     居中      |         右对齐 | 左对齐         |
+| :-----------: | -------------: | :------------- |
+| 居中使用`:-:` | 右对齐使用`-:` | 左对齐使用`:-` |
+|       b       |      aaaaaaaaa | aaaa           |
+|       c       |           aaaa | a              |
+```
+
+::: tip
+
+第二行表示对其方式的 `:` 不是必须的，当没有时，会默认为居左。
+
+:::
+
+### 代码
+
+#### 行内代码
+
+```md
+行内代码效果: `code`
+```
+
+行内代码效果: `code`
+
+#### 块级代码
+
+````md
+```js
+var foo = function (bar) {
+  return bar++;
+};
+
+console.log(foo(5));
+```
+````
+
+三个反引号后跟随代码块语言：`md`、`js`、`plain`（纯文本） 等。
+
+预览：
+
+```js
+var foo = function (bar) {
+  return bar++;
+};
+
+console.log(foo(5));
+```
+
+### 告示块
+
+#### 提示
+
+::: tip
+
+这是一个提示
+
+:::
+
+```md
+::: tip
+
+这是一个提示
+
+:::
+```
+
+#### 备注
+
+::: note
+
+这是一个备注
+
+:::
+
+```md
+::: note
+
+这是一个备注
+
+:::
+```
+
+#### 注意
+
+::: warning
+
+这是一个警告
+
+:::
+
+```md
+::: warning
+
+这是一个警告
+
+:::
+```
+
+#### 警告
+
+::: danger
+
+这是一个警告
+
+:::
+
+```md
+::: danger
+
+这是一个警告
+
+:::
+```
+
+### 脚注
+
+```md
+这是一段文本[^1]
+
+[^1]: 这是一个脚注
+```
+
+仅支持 `[^1]` 风格的脚注，脚注内容就近放置，以方便阅读源文本。
+
+### 引用
+
+```md
+这是一段正文文本
+
+> 这是一段引用文本
+
+这是另一段正文文本
+
+```
+
+::: tip
+
+除上述文字样式外，不使用 html 语法改变文字样式，仅在特殊情况下使用 html 语法增添文档的趣味性。
+
+:::

src/contributors.md

@@ -11,3 +11,5 @@ icon: group
 需要将原语雀贡献者同步过来。
 
 :::
+
+[![contributors](https://contrib.rocks/image?repo=zotero-chinese/wiki)](https://github.com/zotero-chinese/wiki/graphs/contributors)