Merge pull request #39 from servicemesher/feature/add-md-guideline

添加md语法规范

docs/content-guide.md

@@ -1,8 +1,10 @@
-# 内容管理指南
+## 内容管理指南
 
 本站除主页外的所有内容都是用 Markdown 格式文档编写，然后由 Hugo 渲染出 HTML 页面。所有的 Markdown 内容都保存在 `content` 目录下。
 
-## 默认模板
+Markdown规则与翻译规范参考[Markdown 语法规范](./markdown-guide.md)。
+
+### 默认模板
 
 创建博客的默认模版位于 `archetypes/default.md`。
 
@@ -46,7 +48,7 @@ keywords: [""]
 
 注意：页面右侧的“分类”和“标签“显示的是所有博客的，而非当前博客页面的”分类“和”标签“。
 
-## 创建新的博客
+### 创建新的博客
 
 如果需要创建新的博客，只需要运行下面的命令：
 
@@ -57,7 +59,7 @@ touch content/blog/new-blog/index.md
 
 打开 Markdown 文件，修改文档的元数据，然后就可以欢快的编辑内容了。
 
-## 创建新的 tab 页面
+### 创建新的 tab 页面
 
 使用下面的命令创建新的 tab 页面：
 
@@ -71,9 +73,9 @@ hugo new new-tab.md
 
 ```toml
 [[menu.main]]
-	name = "新的页面"
-	url = "/new-tab/"
-	weight = 6
+    name = "新的页面"
+    url = "/new-tab/"
+    weight = 6
 ```
 
 - name：tab 显示在主页上的名称

docs/markdown-guide.md

@@ -0,0 +1,227 @@
+## Markdown 语法规范
+
+### 标题和章节
+```
+---
+title: This is the title 文章标题
+---
+
+## This is heading 2 / 二级标题
+
+### This is heading 3 / 三级标题
+
+#### This is heading 4 / 四级标题
+
+```
+
+- 文章标题只在文档 front matter 中使用 `title` 属性定义。不使用 heading 1 (`#`)。
+- 章节标题使用 heading 2、3 或 4。尽量避免使用 heading 5 (`#####`) 或更多层级的标题。
+- 避免跳层级使用，即 heading 2 段落下的子标题应使用 heading 3 而不是 4。
+- 避免手动给标题添加编号。手动编号增加维护成本。
+- 英文标题使用 sentence case，只有首字母和专有名词大写。
+
+
+### 字体
+
+```
+这段文字 **加粗** ，也可以这样 __加粗__
+
+这段文字 *斜体* 
+
+这段文字 ***加粗且斜体***
+```
+
+- 介绍关键术语时使用 **加粗**，而不是 *斜体* 或“引号”。
+- 避免对以下元素使用加粗或斜体。应统一使用行内代码 `code` 模式标记以下元素：
+	- 文件名
+	- 文件路径
+	- 方法名
+	- 参数、变量名
+	- URL
+
+### 列表
+
+
+列表分为 **有序列表** (ordered list) 和 **无序列表** (unordered list)。
+
+- **有序列表**：强调顺序。如果列表中任意两条对换顺序会影响结果，则使用有序列表，否则使用无序列表。多用于操作步骤等场景。 
+- **无序列表**：调整顺序不影响内容。多用于特性列表、必要条件列表等场景。
+
+**示例**
+```
+	按照以下步骤创建工程：
+	1. 准备开发环境
+		- JDK 7 或 JDK 8
+		- Apache Maven 3.2.5 或以上版本
+	1. 构建工程模板
+		1. 子步骤1
+		1. 子步骤2
+	1. 引入 xxx 依赖
+```
+**结果**
+按照以下步骤创建工程：
+
+1. 准备开发环境
+	- JDK 7 或 JDK 8
+	- Apache Maven 3.2.5 或以上版本
+1. 构建工程模板
+	1. 子步骤1
+	1. 子步骤2
+1. 引入 xxx 依赖 
+
+
+### 表格
+
+大的表格可以直接截图。
+
+
+### 代码
+
+#### 行内代码
+
+```
+在工程的 `pom.xml` 文件中添加配置 xxx
+```
+
+以下类别的内容使用行内代码标记：
+	- 文件名
+	- 文件路径
+	- 方法名
+	- 参数、变量名
+	- URL
+
+
+
+#### 代码块
+
+```
+This is a code block
+```
+
+- 指明代码语言
+  ```
+  \```java
+  ```
+
+
+  \```xml
+
+
+  \```json
+
+  \```sql 
+
+    ```
+- 标明占位符
+  ```
+  $ cd <your_path>/conf
+  ```
+
+
+### 引用
+
+```
+> **说明：**
+> 这是个说明。
+ 
+
+> **重要：**
+> 这是条重要信息。
+
+
+> **重要：**
+> - 不要使用引用格式展示代码内容。
+> - 列表内容2 
+```
+
+> **重要：** 不要使用引用格式展示代码内容。应使用代码块 \`\`\` 格式展示代码。 
+
+
+### 图片
+
+- 图片统一使用 `png` 格式，源文件与引用该图的 markdown 文件放在统一目录下。
+- 确保图片内容有对应的文字说明，防止读者遗漏图片中的重要信息。
+- 插入图片时提供 alt text
+- 不要以截图形式提供代码示例
+
+### 标点
+
+
+- 在中文文档中使用中文全角标点。不要混用中英文标点。
+	`这是一个句子。This is a sentence.`
+	`使用省略号…… 而不是三个点...`
+- 中英文之间保留一个英文空格。 `中文和 English words 之间保留一个空格。`
+
+### 英文
+
+
+
+## 写作风格
+
+### 句意清晰，用词准确，避免复杂句式
+
+**区分 "可以" / "必须"**
+- **可以**（can / could）：表示用户有选择权，可以做也可以不做，或通过其它方法完成。
+  例如：`可以通过修改xx参数值完成yy设置` 可能引起的疑问：修改参数值是否为完成yy设置的必须步骤？不做会怎么样？默认情况是怎样的？修改参数是否是完成设置的唯一方法？其它方法是什么？如何选择？
+- **必须**（must）：表示必要条件，不做会影响结果。
+  例如：`要使用 xxx，必须在工程中引入 xxx 依赖` 表示如果不引入依赖，将无法使用 xxx。
+- 需要（need）：避免使用。
+
+
+**谨慎使用 “一般”“正常”**
+例如：`一般情况` 是指怎样的情况？例外情况是怎样的？什么条件下会出现例外？例外如何处理？
+
+
+### 避免冗余
+
+- 错误：`这个配置没有什么特殊的,正常使用即可`  （去掉这句话不影响文意）
+
+
+### 避免口语化表达
+
+### 正确使用 “的”“地”“得”
+
+### 使用代词时要有明确的指代对象，避免歧义
+
+
+- 错误：`把它设为 true`
+- 正确：`把xxx配置项设为 true`
+
+
+### 避免使用 “我们”
+
+尽量使用祈使句 / 第二人称。
+	- 错误：“我们发送一个请求”
+	- 正确：“发送请求”
+
+
+### 避免使用缩写
+
+- 为了让所有读者都更易读懂文档，尽量使用全称。例如：使用 Kubernetes, 而不是 k8s。
+- 避免拉丁缩写，例如："i.e." "e.g." "etc." "et al."
+
+### 使用主动句，避免被动语态
+
+- 错误：`请求被收到后，服务器开始执行xxx`
+- 正确：`服务器收到请求后，开始执行xxx`
+
+**例外：**
+
+- 强调状态而非动作。如：`确认文件已被保存。`
+- 没有必要提及主语或动作执行者。
+
+### 表述直接，避免否定句，尤其不要使用双重否定句
+
+
+- 错误：`没有管理员权限的用户不能删除文件。`
+- 正确：`要删除文件，用户必须拥有管理员权限。`
+
+
+### 避免拟人化表达
+- 错误：`xx参数告诉服务器要执行xxx`
+- 正确：``	
+
+### 禁止涉及性别、法律、文化等
+
+- 不要使用“他、她、他/她”等有性别指代的词。优先改写句子，不可避免时，使用复数“他们”或者“用户”。
+- 不要提及圣诞、春节等有特定文化背景的场景。