标签:Markdown 规范 列表 空格 item fruit 使用 标题
参考文章
- 参考 :【Markdown: Syntax】
- 参考 :【Markdown 书写风格指南】
- 参考 :【Markdown Style Guide】
- 参考 :【Markdown 书写风格规范及美化】
- 参考 :【令人惊艳的博客】
通用规则
文件
文件扩展名使用:
.md
.- 文件名:
- 用小写代替大写
- 把开头 the , a , an 除去
- 用连字符:
-
, 代替标点和空格 - 用一个连字符代替连续多个连字符,当多个连字符出现时,只使用一个
- 不在文件名前后使用连字符
建议命名格式:
file-name.md
空白
新行:
不要 使用连续两空行,也就是说,不要连续使用两个换行符,除非是在代码块中不得已而必须出现。
以回车换行结束文件。不要在文件结束时留下空行。
不要在行尾留空格,除非是在行尾空出两个空格插入换行符
- 建议使用:
```
只使用了一行空行来分隔- list
- list
# Header
```
句子结束空格:句子结束使用一个空格分隔
- 例如:
`First sentence. Second sentence.
- 例如:
自动换行
尝试将一行限制在 80 个字符以下,将长段落按照以下的逻辑分开,例如:
- 句子: 一句话结束 . 之后, 问句问号 ? 或者感叹句 ! 之后
- 子句 clauses: 在单词 and, which, if ... then, 逗号 , 之后
- 短语 phrases
- 句子: 一句话结束 . 之后, 问句问号 ? 或者感叹句 ! 之后
设置你的文本编辑器对 Markdown 文件一行不要超过80字符,以免忘记。
代码
- 不要 在 shell 代码前加 $ 符号,除非你想要展示命令的输出。
- 建议使用:
echo a echo a > file
- 建议展示输出:
$ echo a a $ echo a > file
建议, 在代码前标明代码语言:
```
Use the following Bash code:echo a
echo a > file
```
- 建议使用:
- 标记代码内容:使用代码块,或者行内代码
- 可执行文件:
`gcc` is the best compiler available.
- 文件路径
- 程序版本号
- 大写的缩写解释
xinetd stands for `eXtended Internet daemon`
- 其他和电脑相关的术语,想要单独标明
- 可执行文件:
- 不要标记为代码
- 项目名。 比如: GCC
- 函数库名。比如: libc, glibc
拼写和语法
使用正确的拼写和语法。
尽量选用英语,更准确的说美式英语。
类似 URL 或者代码,添加代码标记,这样拼写检查程序会自动忽略。
注意大小写敏感的拼写错误,尤其是项目名,品牌名,或者缩写。
- 建议使用: URL, LinkedIn, DoS attack
- 不建议: url, Linkedin, dos attack
- 建议使用: URL, LinkedIn, DoS attack
避免使用非正式的缩写。
- 建议使用: biography, repository, directory
- 不建议: bio, repo, dir
- 建议使用: biography, repository, directory
区块
换行符
- 避免使用换行符, 因为他们没有被广泛认可的语义。在少数确实需要使用的时候,在行尾使用两个空格。
标题
标题基本格式
- 在 # 和标题之间加入一个空格。
不建议使用,其中
#..Header.
表示空格:
```
#Header
```
- 不要 使用闭合的 # .
- 不建议使用,其中
.
表示空格:
# Header #
- 不建议使用,其中
- 不要 在 # 前加入空格.
- 不建议使用,其中
.
表示空格:
.# Header
- 不建议使用,其中
- 不要 跳跃使用标题等级.
- 在标题上下用空行隔开,除非标题在文档开头。
- 避免 在相同 Markdown 文件中使用相同的标题.
- 使用范例:
建议使用:
```
# Header 1## Header 2
### Header 3
```
顶级标题
- 如果你想要 HTML 直接输出,这样唯一的 h1 标记就是输出的第一件事,并且会成为文档的标题。这就是HTML的顶级标题。
- 建议不使用(不了解)
标题大小写
- 标题开头使用大写字母,除非标题内容总是以小写出现, 例如,计算机代码。
- 标题第一个单词后的其他单词的首字母按照句子中原始大小写。
- 建议使用:
# The header of the example
- 不建议:
# The Header of the Example
- 建议使用:
标题结尾
- 使用
---
# Header
---
Content
标题的长度
- 保证标题越短越好。
- 避免使用长句子,总结长句子作为标题。 然后将长句子作为标题下的第一小节
建议使用
# Huge header
Huge header that talks about a complex subject.
不建议:
# Huge header that talks about a complex subject
标题结尾标点
- 不要使用诸如: 冒号
:
, 句号.
之类的标点符号结尾。
标题同义词
标题用作用户索引的关键词,由于这个原因,你可能希望在标题中用多个关键词。
创建一个同层级的同义词标题在主标题之前,并且标题下不包含内容:
建议使用:
每一个同层级的空标题都假定是同义的 # Purchase # Buy You give money and get something in return.
如果层级不一样,那就是另外的含义:
例如:
# Animals ## Dog
引用
在符号
>
后面接一个空格。在每一行使用 > 符号,包括换行的句子。
不要在单独的引用中使用空行。
建议使用:
> a > > b
不建议使用:
```a
b
```
列表
列表基本语法
- 无序列表:
- 使用连字符 - , 尽量不要使用
*
号和+
.
- 使用连字符 - , 尽量不要使用
有序列表:
- 尽量选用
1.
来标记有序的列表, 除非你打算通过数字在相同 Markdown 文件或者外部文件中引用他们。 - 尽量使用无序的列表,除非有通过数字引用的需求。但是如果在原有有序列表中间加入新的列表,原有的引用会被破坏。
- 尽量选用
可接受的, 使用文本引用:
The ouput of the `ls` command is of the form: drwx------ 2 ciro ciro 4096 Jul 5 2013 dir0 drwx------ 4 ciro ciro 4096 Apr 27 08:00 dir1 1 2 Where: 1. permissions 2. number of files directory contains
可接受,通过外部 markdown 文件引用:
Terms of use. 1. I will not do anything illegal. 2. I will not do anything that can harm the website.
如果新列表项被加入,引用会破坏。尽量减少这种问题:
- 保证引用靠近列表,这样作者会更少可能的忘记去更新
- 当从外部引用时,总是引用到一个固定版本的 markdown 文件
- 保证引用靠近列表,这样作者会更少可能的忘记去更新
列表项中的空格
- 列表项标记前总是留有一个空格。
```a
b
c
a
b
c
```
列表内容的缩进
- 列表中内容的缩进层级必须和第一个列表项一致
```item 1
Content 1
item 2
Content 2
```
列表中的空行
- 如果每一个列表项只有一行, 不要在列表项之间增加空行。
- item 1 - item 2 - item 3
- 如果某一列表项不止一行,在每一个列表项之间增加空行。
```item that
is wrappeditem 2
- item 3
```
- 列表嵌套:
```item 1
- item 11
- item 12
- item 13
item 2
item 3
```
列表外的空行
列表外建议留有一空行
Before. - list - list After.
列表项首字母大小写
每一个 list 使用原来在句子中的大小写
I want to eat: - apples - bananas - grapes
列表项结尾标点
列表项结尾标点,除非:
- 包含多个句子或者短语
- 以大写字母开头,添加标点
- 否则, 如果以句号结尾的话,省略标点.
建议使用:
不含标点 - apple - banana - orange 包含多个句子 - go to the market - then buy some fruit. Bad for wallet. - finally eat the fruit. Good for tummy. 包含非句号 - go to the marked - then buy fruit? - of course! 大写字母开头 - Go to the market. - Then buy some fruit. - Finally eat the fruit. 多段落 - go to the market - then buy some fruit. Bad for wallet. - finally eat the fruit. Good for tummy.
定义列表
- 避免 使用定义列表扩展,因为他并没有被多数实现,也没有出现在 CommonMark
若要使用,格式化列表:
用加粗,链接,或者代码,格式化需要定义的内容
加粗 - **apple**: red fruit - **dog**: noisy animal - **apple**: red fruit. Very tasty. - **dog**: noisy animal. Not tasty. 链接 - [apple](http://apple.com): red fruit - [dot](http://dog.com): red fruit 代码 - `-f`: force - `-r`: recursive
将内容和定义使用冒号和空格分割 :.
不要对齐定义,这样难以维护,并且不会显示在 HTML 输出
不建议下面这样的,冒号或者冒号后面的文字定义对齐 - **apple**: red fruit - **dog**: noisy animal
代码区域
code fence blocks
不要 缩进 fenced code blocks.
- 总是指定代码的语言
a = 1
标签:Markdown,规范,列表,空格,item,fruit,使用,标题 来源: https://www.cnblogs.com/bogonogob/p/10421084.html
本站声明: 1. iCode9 技术分享网(下文简称本站)提供的所有内容,仅供技术学习、探讨和分享; 2. 关于本站的所有留言、评论、转载及引用,纯属内容发起人的个人观点,与本站观点和立场无关; 3. 关于本站的所有言论和文字,纯属内容发起人的个人观点,与本站观点和立场无关; 4. 本站文章均是网友提供,不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属;如您发现该文章侵犯了您的权益,可联系我们第一时间进行删除; 5. 本站为非盈利性的个人网站,所有内容不会用来进行牟利,也不会利用任何形式的广告来间接获益,纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。