这里是前言部分,采用正文格式,无需标题
在每一篇 Handbook 的开头,我们建议首先编写一小段本页内容的介绍,作为本篇的前言,使得你的读者能够快速抓取到本页内容所围绕的核心。
根据你所要编写的内容不同,前言部分可以进行灵活编排。例如在部门介绍页,可以是部门职能一段话概括;在概念介绍页,可以是主题的名词解释(比如:OKR ,即目标与关键成果法,是一套明确和跟踪目标及其完成情况的管理工具和方法),在工具指南页,可以插入相关页面进行快速引导等等。
例如:
欢迎访问极狐 Gitlab Handbook 编写模板,您可以将本页作为模板来编写自己部门的 Handbook 。
如果想了解如何使用 Markdown 语言编写 Handbook ,请在 Markdown 指南 进行查询。
不要使用标题格式来进行正文内容的介绍,标题尽量短而精。
需要注意标题级别与标题的格式,标题前后空一行。
我们不使用一级标题,因为它已经作为页面标题显示在每个页面开头位置,我们建议的标题级别分为:二级标题、三级标题、四级标题。尽可能将一篇文章的标题的级别控制在这三个等级以内。
编号也是常常用来表达逻辑结构和层级内容的方式,合理使用编号能让你的页面看起来既整洁又有重点。
我们建议,当你要阐述的内容需要以条目形式呈现时才使用编号,大段的内容通常采用正文格式直接阐述。 编号也有级别,尤其是当你需要展现到嵌套的条目时。 我们建议的编号级别分为三个等级,如同标题一样,你需要按照级别次序依次使用正确的编号。两种编号可以视情况进行嵌套。
这是编号使用的另一种情况。
正文通常采用的是 Markdown 默认的,没有其他效果的呈现方式,直接输入正文内容即可。
有以下几个方面需要注意:
我们欢迎在 Handbook 中采用图表来直观形象地表达您所想传达的内容。
使用图表需要注意以下几点:
下面是本页内容的 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)