【经验分享】如何使用Markdown编写技术文档？

嵌入式物联网开发 2022-08-20 1354

描述

1 概述

Markdown是一种轻量级标记语言，创始人为约翰·格鲁伯（英语：John Gruber）。它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。

由于Markdown的轻量化、易读易写特性，并且对于图片，图表、数学式都有支持，许多网站都广泛使用Markdown来撰写帮助文档或是用于论坛上发表消息。如GitHub、Reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge、简书等，甚至还能被使用来撰写电子书。

2 几种支持Markdown语法的工具、软件介绍

2.1 Typroa

Typroa 是我常用的编辑器，熟悉了Markdown语法了，你会用起来非常顺手。它的设计与别人编辑器最大的区别是，它支持 “所见即所得”，一边编写，立马就预览，效率高，也很流畅。

特色功能：可以支持外部图床设置，直接把截图贴上来，立马可以上传到图床，生成访问链接，这个功能非常暂。

2.2 sublime插件

可以参考这个链接尝试安装看看，不过我试了，效果并不理想。

2.3 Cmd Markdown

这个有点特别，它既支持在线网页编辑器，也支持本地化的编辑器。采用的是左编辑、右预览的设计。新手可以考虑使用下。

2.4 在线云笔记之类的平台

有道云笔记：使用了，不太符合我的习惯；不过作为在线笔记倒是可以考虑。

语雀笔记：没使用过，感兴趣可以尝试下。

印象笔记: 没有使用过，感兴趣可以尝试下。

还有其他。。。

2.5 技术博客平台的编辑器

常见的技术博客平台，比如CSDN、简书、博客园、oschina.net等都支持Markdown版本的编辑器。

2.6 总结

萝卜青菜，各有所爱！选择一款适合自己的，多使用，孰能生巧！

3 常用语法

3.1 目录相关

1 这是1级目录

1.1 这是2级目录

1.1.1 这是3级目录

1.1.1.1 这是4级目录

1.1.1.1.1 这是5级目录

1.1.1.1.1.1 这是6级目录

注意，一般最大支持 6 级目录，这样满足我们的日常写作需求了。

3.2 文本相关

这个是加粗！ 这个是斜体！ 这个是斜体加粗！ ~~这个是字体删除！~~这个是文字加底色 (实则是代码的写法，下面会讲)

3.3 列表相关

ggg

fff

有序列表4（加粗）

有序列表3

有序列表2

有序列表1 a. 有序列表 b. 有序列表

（数字加 . 加空格；支持多级嵌套）

无序列表

哈哈哈

无序列表

（-或*或+ 加空格；支持多级嵌套）

3.4 代码相关

这是单行代码：printf("hello world!\r\n");

int main(void)

{

printf("hello world!\r\n");

return 0;

}

3.5 图片相关

编辑器

语法规则:

3.6 超链接相关

这里是百度的超链接描述

语法规则: 描述

3.7 文字引用

这是一段引用文字

引用可以嵌套

引用可以嵌套这是一段引用文字

3.8 水平分隔线

【三个横杆或三个星号或三个下划线，+ 回车】

3.9 表格相关

（左对齐）表头1	（居中）表头2	(右对齐)表头3	默认表头
内容1	内容2	内容3	内容4
~~内容1~~	内容2	内容3	内容4

4 高阶功能

4.1 to-do-list

[x] done-list-3

[x] done-list-2

[x] done-list-1

[ ] to-do-list-3

[ ] to-do-list-2

[ ] to-do-list-1

4.2 流程图

st=>start: Start

op=>operation: Your Operation

cond=>condition: Yes or No?

e=>end

st->op->cond

cond(yes)->e

cond(no)->op

st=>start: 开始框

op=>operation: 处理框

cond=>condition: 判断框(是或否?)

sub1=>subroutine: 子流程

io=>inputoutput: 输入输出框

e=>end: 结束框

st(right)->op(right)->cond

cond(yes)->io(bottom)->e

cond(no)->sub1(right)->op

st=>start: 开始框

op=>operation: 处理框

cond=>condition: 判断框(是或否?)

sub1=>subroutine: 子流程

io=>inputoutput: 输入输出框

e=>end: 结束框

st->op->cond

cond(yes)->io->e

cond(no)->sub1(right)->op

4.3 时序图

Alice->Bob: Hello Bob, how are you?

Note right of Bob: Bob thinks

Bob-->Alice: I am good thanks!

【注意：这个不是每个Markdown编辑器都支持的渲染功能】

Title: 标题：复杂使用

对象A->对象B: 对象B你好吗?（请求）

Note right of 对象B: 对象B的描述

Note left of 对象A: 对象A的描述(提示)

对象B-->对象A: 我很好(响应)

对象B->小三: 你好吗

小三-->>对象A: 对象B找我了

对象A->对象B: 你真的好吗？

Note over 小三,对象B: 我们是朋友

participant C

Note right of C: 没人陪我玩

4.4 甘特图

title 项目开发流程

section 项目确定

需求分析 :a1, 2016-06-22, 3d

可行性报告 :after a1, 5d

概念验证 : 5d

section 项目实施

概要设计 :2016-07-05 , 5d

详细设计 :2016-07-08, 10d

编码 :2016-07-15, 10d

测试 :2016-07-22, 5d

section 发布验收

发布: 2d

验收: 3d

【注意：这个不是每个Markdown编辑器都支持的渲染功能（Cmd Markdown 的 gantt语法）】

%% 语法示例

gantt

dateFormat YYYY-MM-DD

title 软件开发甘特图

section 设计

需求 :done, des1, 2014-01-06,2014-01-08

原型 :active, des2, 2014-01-09, 3d

UI设计 : des3, after des2, 5d

未来任务 : des4, after des3, 5d

section 开发

学习准备理解需求 :crit, done, 2014-01-06,24h

设计框架 :crit, done, after des2, 2d

开发 :crit, active, 3d

未来任务 :crit, 5d

耍 :2d

section 测试

功能测试 :active, a1, after des3, 3d

压力测试 :after a1 , 20h

测试报告 : 48h

【注意：这个不是每个Markdown编辑器都支持的渲染功能（Typroa 的 mermaid语法）】

4.5 数学公式

这是单行公式$E=mc^2$

$\sin(\alpha)^{\theta}=\sum_{i=0}^{n}(x^i + \cos(f))$

$$ E=mc^2 $$

$$ \sin(\alpha)^{\theta}=\sum_{i=0}^{n}(x^i + \cos(f)) $$

5 注意事项

5.1 空格问题

Markdown对空格是不敏感的，也就是说你想输入空格显示的时候，还需要特殊操作，比如首行空两个的写作场景。

半角的空格全角的空格

5.2 换行问题

操作方法

行尾打两个或两个以上的空格之后回车（换行后的行距较小）

打两个回车（换行之后的行距变大）

html的
来换行（比较兼容的写法）

这是一行
这是另一行这是第3行

这是一行

这是另一行

这是第3行

这是一行
这是另一行
这是第3行

5.3 字符转义的问题

在 HTML 文件中，有两个字符需要特殊处理： < 和 & 。 < 符号用于起始标签，& 符号则用于标记 HTML 实体，如果你只是想要使用这些符号，你必须要使用实体的形式，像是 < 和 &。

这里举两个例子：

AT&T AT&T

4 < 5 4 < 5

5.4 内嵌 HTML 标签的问题

我也不熟，很少有，举个例子：

这是红色字体

这是绿色字体

字体大小size=1

字体大小size=3

字体大小size=5

【注意：以上html标签有些编辑器又不支持】

审核编辑：刘清

打开APP阅读更多精彩内容