tipi/WRITTEN_STANDARDS at master · luyinhua/tipi

Repository navigation

# TIPI编写规范

## 标题编写

在编写内容的时候需要一个清晰的层次关系，适当的根据内容进行划分，需要遵守如下规则:

* 最多只能包含一个一级标记。一页内容中通常需要包含一个一级标题（也就是#），最多也也只能包含一节标题。

* 层级之间是递进关系。标题层级的选中需要更具内容的层级关系进行，子级内容需要比父级内容大一个级别，

不允许出现级别之间的跳跃，

* 不允许出现层级跳跃。比如: 1级下面不允许直接出现3级标题，需要有层级关系。

* 内容和层级标示（#）之间需要也只能使用一个**空格**。

## 正文编写

正文作为内容的主体也需要一定的规范。

* 内容最大宽度不能太大。每一行的最大宽度尽量保持在**80**左右，需要适当的进行断句。

但是一条完整的句子不要在中间进行换行，因为这样会多出一个空格。

* 注意正文中的内容及代码**不要出现全角的英文字符**

### 段落的使用

正文内容需要进行适当的分段，根据上下文或者内容的组织对内容进行分段将有利于读者的阅读。

## 列表的编写

对于没有明显先后顺序的列表使用无序列表，否则使用有序列表。

## 标点符号的使用

* 半角全角的使用: 在中文段落上下文中使用全角符号，如果是在英文上下文环境则统一使用半角符号。

## 代码块的编写

## Markdown中的HTML

有时需要表现一些特定的内容，而markdown似乎又无法满足需求时能否使用HTML这个问题需要根据情况而定，

如果我们真的只是为了表现形式内容先不要贸然直接用HTML编写，有可能可以通过其他的手法来展现。