软件工程师使用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, 在我的推广下, 同事们逐渐接受了这种文档编写方式, 并开始大规模在项目中使用.