Handbook 模板

维护者:

这里是前言部分，采用正文格式，无需标题
在每一篇 Handbook 的开头，我们建议首先编写一小段本页内容的介绍，作为本篇的前言，使得你的读者能够快速抓取到本页内容所围绕的核心。
根据你所要编写的内容不同，前言部分可以进行灵活编排。例如在部门介绍页，可以是部门职能一段话概括；在概念介绍页，可以是主题的名词解释（比如：OKR ，即目标与关键成果法，是一套明确和跟踪目标及其完成情况的管理工具和方法），在工具指南页，可以插入相关页面进行快速引导等等。
例如：
欢迎访问极狐 Gitlab Handbook 编写模板，您可以将本页作为模板来编写自己部门的 Handbook 。
如果想了解如何使用 Markdown 语言编写 Handbook ，请在 Markdown 指南进行查询。

标题与编号的使用（二级标题）

不要使用标题格式来进行正文内容的介绍，标题尽量短而精。

标题的使用（三级标题）

需要注意标题级别与标题的格式，标题前后空一行。

标题的级别（四级标题）

我们不使用一级标题，因为它已经作为页面标题显示在每个页面开头位置，我们建议的标题级别分为：二级标题、三级标题、四级标题。尽可能将一篇文章的标题的级别控制在这三个等级以内。

标题与标题之间（四级标题）

不同级别的标题应当依次嵌套，不要在一个二级标题下直接使用四级标题。
保证你的同级标题之间是平行的概念，正如本文一样。
标题与标题之间需要有内容，尽量不在一个标题下直接承接另一个标题。

编号的使用（三级标题）

编号也是常常用来表达逻辑结构和层级内容的方式，合理使用编号能让你的页面看起来既整洁又有重点。

编号的使用条件（四级标题）

我们建议，当你要阐述的内容需要以条目形式呈现时才使用编号，大段的内容通常采用正文格式直接阐述。编号也有级别，尤其是当你需要展现到嵌套的条目时。我们建议的编号级别分为三个等级，如同标题一样，你需要按照级别次序依次使用正确的编号。两种编号可以视情况进行嵌套。

无序编号

当你展现的条目之间是平行关系时采用无序编号。（这是一个一级编号）
在采用无序编号的时候要注意一下几点：
- 在没有嵌套内容时优先采用一级编号（这是一个二级编号）。
- 当你的条目≥ 2 时才使用编号。
- 不要单独一句话使用一个编号，这种时候应当以正文格式呈现。
- 列表空行问题：
  - 当列表结束时，需要在这样的列表条目后空一行再接后面的内容。（这是一个三级编号）
  - 不空一行会导致格式错误。
  - 在一个列表内不要空行，列表之间用空行隔开。

有序编号

这是编号使用的另一种情况。

当你展现的条目之间有递进关系或先后次序。
在编写的时候可以都写"1."， Markdown 会自动识别序号
1. 但在使用有序编号进行嵌套的时候要格外注意编号级别
2. 因为有序编号的三个级别编号是一样的，只有缩进值的差别。
  1. 当编号的嵌套达到三级，尽可能使用无序编号。
  2. 无序编号更容易识别内容的级别，更好展现嵌套的逻辑。

正文内容

正文通常采用的是 Markdown 默认的，没有其他效果的呈现方式，直接输入正文内容即可。
有以下几个方面需要注意：

正文中，英文单词和数字需要和其他中文段落间用空格隔开。当它被括号括起来时则在括号外空格。
例如：极狐 Gitlab 成立于 2021 年，致力于为中国用户提供一站式覆盖软件开发生命周期的开放一体化 DevOps 平台。
而不是：极狐Gitlab成立于2021年，致力于为中国用户提供一站式覆盖软件开发生命周期的开放一体化DevOps平台。
正文中需要强调的重点部分采用加粗，斜体等方式进行适当的标注，尽量避免大段落的无重点内容。
正文通常不需要首行缩进。
正文内容中涉及到英文专有名词的部分需要首字母大写。
通常在使用某个英文缩写的时候需要先呈现合适的中文翻译，在后文中再使用缩写。
例如：当您需要带薪休假 (PTO) 时需要提前与部门经理进行沟通，确认 PTO 的时间。

插入图表

我们欢迎在 Handbook 中采用图表来直观形象地表达您所想传达的内容。
使用图表需要注意以下几点：

确保您的图片质量，使其在页面上足够清晰。
不要使用文字图片，PPT截图来替代您的正文内容。也就是说，当您的图片仅仅传达文字信息时，请用正文文字内容。
图片和表格前后都需要空一行，与正文段落隔开。
尽量为您的图片或者表格进行题注，可以以正文居中的方式呈现。
关于在 Handbook 中插入图片和表格的其他问题，请查阅 Markdown 指南

本页的 Markdown 呈现

下面是本页内容的 Markdown 原代码，您可以依照本模板进行自己内容的编排。

## 标题与编号的使用（二级标题）

不要使用**标题格式**来进行**正文内容**的介绍，标题尽量**短而精**。

### 标题的使用（三级标题）

需要注意标题级别与标题的格式，**标题前后空一行**。

#### 标题的级别（四级标题）

我们不使用一级标题，因为它已经作为页面标题显示在每个页面开头位置，我们建议的标题级别分为：二级标题、三级标题、四级标题。尽可能将一篇文章的标题的级别控制在这**三个等级**以内。

#### 标题与标题之间（四级标题）

- 不同级别的标题应当依次嵌套，不要在一个二级标题下直接使用四级标题。  
- 保证你的同级标题之间是平行的概念，正如本文一样。
- 标题与标题之间需要有内容，尽量不在一个标题下直接承接另一个标题。

### 编号的使用（三级标题）

编号也是常常用来表达逻辑结构和层级内容的方式，合理使用编号能让你的页面看起来既整洁又有重点。  

#### 编号的使用条件（四级标题）

我们建议，当你要阐述的内容需要以**条目形式**呈现时才使用编号，大段的内容通常采用正文格式直接阐述。
编号也有级别，尤其是当你需要展现到嵌套的条目时。  我们建议的编号级别分为**三个等级**，如同标题一样，你需要按照级别次序依次使用正确的编号。**两种编号可以视情况进行嵌套**。    

#### 无序编号

- 当你展现的条目之间是平行关系时采用无序编号。*（这是一个一级编号）*
- 在采用无序编号的时候要注意一下几点：
   - 在没有嵌套内容时优先采用一级编号*（这是一个二级编号）*。
   - 当你的条目≥ 2 时才使用编号。
   - 不要单独一句话使用一个编号，这种时候应当以正文格式呈现。
   - 列表空行问题：
       - 当列表结束时，需要在这样的列表条目后空一行再接后面的内容。*（这是一个三级编号）*
       - 不空一行会导致格式错误。
       - 在一个列表内不要空行，列表之间用空行隔开。

#### 有序编号

这是编号使用的另一种情况。
1. 当你展现的条目之间有递进关系或先后次序。
2. 在编写的时候可以都写"1."， Markdown 会自动识别序号
   1. 但在使用有序编号进行嵌套的时候要格外注意编号级别
   2. 因为有序编号的三个级别编号是一样的，只有缩进值的差别。
      1.  当编号的嵌套达到三级，尽可能使用无序编号。
      2. 无序编号更容易识别内容的级别，更好展现嵌套的逻辑。  

## 正文内容

正文通常采用的是 Markdown 默认的，没有其他效果的呈现方式，直接输入正文内容即可。  
有以下几个方面需要注意：

-  正文中，**英文单词**和**数字**需要和其他中文段落间用空格隔开。当它被括号括起来时则在括号外空格。   
例如：极狐 Gitlab 成立于 2021 年，致力于为中国用户提供一站式覆盖软件开发生命周期的开放一体化 DevOps 平台。  
而不是：极狐Gitlab成立于2021年，致力于为中国用户提供一站式覆盖软件开发生命周期的开放一体化DevOps平台。  
- 正文中需要强调的重点部分采用**加粗**，*斜体*等方式进行适当的标注，尽量避免大段落的无重点内容。
- 正文通常不需要首行缩进。
- 正文内容中涉及到英文专有名词的部分需要首字母大写。
- 通常在使用某个英文缩写的时候需要先呈现合适的中文翻译，在后文中再使用缩写。  
例如：当您需要带薪休假 (PTO) 时需要提前与部门经理进行沟通，确认 PTO 的时间。

## 插入图表

我们欢迎在 Handbook 中采用图表来直观形象地表达您所想传达的内容。    
使用图表需要注意以下几点：

- 确保您的图片质量，使其在页面上足够清晰。
- 不要使用文字图片，PPT截图来替代您的正文内容。也就是说，当您的图片仅仅传达文字信息时，请用正文文字内容。
- 图片和表格前后都需要空一行，与正文段落隔开。
- 尽量为您的图片或者表格进行题注，可以以正文居中的方式呈现。
- 关于在 Handbook 中插入图片和表格的其他问题，请查阅 [Markdown 指南](/handbook/about/edit-guide/markdown-guide)