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