软件工程师使用markdown写文档的正确姿式

软件工程师使用markdown写文档的正确姿式

自从我在github上了解到markdown之后, 对markdown愈来愈爱不释手. 从最开始的工程README, 到我的博客, 再到项目中的各类技术文档, 我都开始使用markdown来编写.

工程师的markdown使用场景

工程中不少须要输入文本的地方均可以引入markdown, 以github为列:

1. 工程README

以上为Netflix开源项目 Hystrix 的README.
项目Logo, 项目简介, wiki入口, 联系方式 包罗万象. 这个排版很简洁明了, 值得借鉴.

2. WIKI文档

github的编辑器默认语法就是markdown, 使用wiki更能支持版本比较的功能.
而其余主流的wiki系统也都加入了支持markdown的插件(好比xwiki, confluence).

3. 工程Issue

4. 我的博客

既然markdown都玩这么熟了, 再用markdown写写博客吧.
目前主流的技术博客系统都支持了markdown编辑器编写文章(segmentfault, oschina 甚至元老级的csdn也支持了).

工程师markdown编辑器的免费方案:

atom+插件

优势: 使用简单. 前端工程师借助于atom, 编辑效率极高.

缺点: 启动速度稍慢, 编辑框没法与预览框同步滚动.

Intellij+插件

优势: 使用简单, 对于后端工程师编辑效率高.

缺点: 启动速度比较慢

Typora

优势: 启动速度快, 所见即所得, 对于小白用户友好.

缺点: 对于编辑功能与预览功能不能分开.

markdown使用中的小技巧

WORD转markdown

pandoc

万能的pandoc能够支持多种格式文本文件相互转换. 但格式上可能会丢失较多的样式(好比表格语法没有正确的转换), 实际工做中使用较少.

saas服务

有个免费的word to markdown服务提供了word到markdown的转换, 但网站速度访问较慢.

typora

typora提供了一个很是简单的word到markdown转换方式: 在typora的预览模式下, 全选word内容并复制进来, 内容就会自动转成mardown格式, 这个功能作的很是棒.

markdown导出PDF文件

atom经过插件支持PDF的导出, 但不支持目录的生成, 但功能较弱.
而typora支持导出为PDF的功能, 且支持目录的生成, 还支持多种主题,更为人性化.

推广效果

有了流行的标准markdown, 再加上便利的编辑工具typora, 在个人推广下, 同事们逐渐接受了这种文档编写方式, 并开始大规模在项目中使用.