使用Markdown写文档

Posted 2020-10-08 小黑的守望

前言

在工作中，我们经常会遇到需要写笔记的情况，无论是交接文档，还是调试日志，很多需要记录的内容。最近小黑刚好解决了自己用Markdown记录的关键点，所以分享一下自己的心得。

你的文档需要管理

文档管理的认知不是一蹴而就的，只有对文档重要性有了深刻的认知，才会端正态度去编写文档。

这里小黑简单总结下自己的文档记录历史。

文档记录的四个阶段

对文档的重视在大四的时候就慢慢开始了，当时刚好学习了一本书，叫做《你的知识需要管理》。大意是每个知识工作者，都需要对自己的知识进行管理，学会学习，学会做记录，学会做总结。通过这本书，对知识的管理开始变得有意识起来，也了解到了知识学习掌握的不同境界，对快速学习一些内容打下了基础。

对文档记录认知的第二个阶段是本科毕设和研究生毕设阶段，这两个阶段刻意的对排版和文档质量有了深入的认知了解，也是学格严格功夫到家养成的习惯。

第三阶段是工作后对文档的认知。刚工作的时候，发现很多地方缺乏必要的文档，很多工作文档也缺乏必要的记录。做软件工程师时间长了，慢慢认知到：软件工程师工作做得不到位，除了软件写的不好，还在于文档写的不好。

第四阶段就是认识了几位文档特别仔细的人。刘大的文档详细认真、学姐的系统方案专业漂亮，同事的文档斟字酌句都给我造成了很深的触动。对文档规范化、详细化也有了彻底的认知。

随着工作时间的增长，慢慢也发现，只有那些愿意把文档写好的软件工程师，才会抱着严谨认真的态度把事情做好。

选用什么工具

有了做笔记的意识，就需要有一个好的工具吧。几经挑选笔记软件，历经有道笔记、印象笔记、文档管理大师。OneNote等，最终决定使用为知笔记作为的文档记录工具。

大多数的笔记软件功能都类似，网上也很多笔记软件的比较，这里只介绍一下小黑的选择依据：
1.首先，这是一个可以做笔记的软件
2.可以多个终端系统同步，包括手机、PC、笔记本
3.同步速度比较快。OneNote就是由于同步速度抛弃的
4.简单易用
这些软件本身选择哪个不重要，看个人习惯程度，最终还是WIZ笔记我觉得使用很习惯，所以就定了下来。

如何开始文档记录

刚开始文档记录的时候非常不习惯，通过模仿和学习一些优秀的笔记才慢慢养成了做文档自己的习惯，如果有兴趣可以阅读以下我是怎样用为知笔记的。
简单来说就是，养成笔记习惯，有意识的控制自己的知识存储，避免用脑袋去完成所有事情的记录。

为知笔记我从2014年开始使用， 到现在一共使用了3年半的时间，越来越离不开文档记录的习惯。从一开始的免费版用到了现在的收费版，对为知的喜欢也不用多说了。

在长达这么长时间的使用中，我积累了大约2500+的笔记，记录了我曾经学习过的各科知识、毕设的调试笔记，工作的种种心得和感悟，也算是自己比较自豪的一件事情。

其中有很多很关键的KB知识就是自己在解决问题后留下的宝贵财富，如下面对TestStand知识的分类

自己记录的一些KB如下

使用Markdown做笔记

上面大部分内容都是为Markdown做笔记做铺垫的，毕竟是近期工作生活的总结嘛。
关于什么是Markdown，为什么使用Markdown大家可以自行百度。我的理解就是，如果你需要大量写作，使用markdown可以让你对文字排版变得简单。

为知笔记很早就有了markdown语法，只要文档名称后缀添加.md就可以支持。而之前的使用中，体验一直不好，包括以下几点：

1. 不能实时预览自己的格式，只能保存后才能观看
2. 不会修改样式，做出来的文档有点素

后来慢慢的使用WIZ自带的编辑器，并辅助快捷键进行文档的编辑，这样过度了有1年的时间。

再次捡回Markdown

再次使用Markdown是由于上一篇文章中，小黑不会排版微信文章，觉得排版非常费事，所以想要使用Markdown简化工作，而此时刚好发现WIZ有了一个新的插件，让Markdown更加直观简单了。

这个插件就是Wiz.Editor.md

使用几天之后，发现好用到爆，完美解决了自己WIZ使用Markdown的所有顾虑。

下面是我认为的非常好用的功能

• 和WIZ兼容的非常完美
• UI非常的简介美观
• 支持双界面预览
• 支持多种主题样式的更换，包括Markdown语法的各种代码高亮显示

升级版本的Markdown编辑

当然，如果说仅仅是这样，使用MarkdownPad也差不多，近期又研究了一下CSS，Markdown渲染出来的文档就相当帮了，主要实现的功能如下：

1. 增加了对h1-h5标题的颜色更改，然不同的标题有更加醒目好看的颜色
2. 增加了h1-h5的标题编号，实现了跟Word一样简单的文档编号功能
3. 调整了一些页面元素的margin，让页面变得更加整齐，最终实现的效果就是这个文档看到的效果，截图如下：

后记

由于篇幅关系，这里只简单介绍一下自己Markdown语法的一些成果，后续有必要再整理详细的操作过程，笔记还是都有的~

来自为知笔记(Wiz)