架构师成长之路工具篇：markdown撰写文档
Posted 玄道公子
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了架构师成长之路工具篇：markdown撰写文档相关的知识，希望对你有一定的参考价值。
今天笔者想说的工具就是markdown， 正所谓工欲善其事必先利其器，选择高效的工具自然能提升工作效率。
笔者使用的markdown工具是： typora
word太重，太复杂， 在写文档的时候，常常为了调整一些格式和排版问题而花费大量时间在互联网上到处搜索，这里显示不出来，那里空白太多等等。
鉴于此，笔者越来越习惯于使用markdown来撰写文档。 不管是API文档，还是模块的设计文档，又或者一些指南性的说明文档等等。
当然，markdown也有缺点， 比如因为markdown是文本文件，所以其内就无法包含图片， 要在markdown中显示图片，就需要指定图片文件的路径。 因此，笔者的习惯是，每当要写文档的时候，就以文档名创建一个文件夹，其内是一个 xxx.md 文件以及一个 images这样一个子文件夹用于存放图片。
现在笔者日常工作中也会涉及不少撰写文档的任务，仍然想使用markdown来完成。 但有一些问题：
- 发布文档一般需要pdf文档
- 发布的文档需要有页眉，页脚，甚至还需要有水印
发布pdf格式这个问题不难，typora就能直接导出pdf格式，但是他无法给导出的文件添加页眉页脚以及水印信息。
这个问题也有两个解决办法，其一， 使用pdf编辑器来添加页眉页脚以及水印等信息，但是有些编辑器无法再页眉或页脚中添加 图形化的logo标志；其二，就是笔者今天想说的，使用typora先将markdown转为html格式， 然后再使用 wkhtmltopdf 工具将 html文件转换为最终的pdf格式，并添加页眉页脚以及水印等信息。
wkhtmltopdf 工具是什么，这里就不赘述了，网上有很多关于它的信息。 这里只记录笔者使用wkhtmltopdf 来将html转换为pdf的过程。
笔者是在Windows写了一个bat脚本来进行转换，免得每次都需要去输入各种参数：
rem call :getname %1
set aa = %~n1
wkhtmltopdf --enable-local-file-access --margin-top 20mm --header-html ./logo.html --header-center %~n1 --header-spacing 10 --margin-bottom 20mm --footer-spacing 10 --footer-line --footer-font-size 5 --footer-left "Page [page]/[topage]" --footer-html ./footer.html %1 %~n1.pdf
pause
将此段bat保存为文件，比如 html2pdf.bat , 然后如果有一个叫做 test.html的文件，将其拖拽到html2pdf.bat文件上，脚本就是自动执行，如果执行成功，会生成 一个叫做 test.pdf 的文件， pdf文件的名称和html文件的名称相同。
注意： 从typora中导出的html文件内的图片路径引用路径和markdown中的路径是一样的， 因此，需要将test.html文件存放在test.md文件 的同一个目录下进行html到pdf的转换，html2pdf则可以放在任何地方
以上的名称中还有两个另外的html文档， logo.html 和 footer.html，前者是用来在页眉处显示一个图片logo的(如公司logo)，后置就是页脚的扩展信息。
wkhtmltopdf 可以通过参数设置页眉页脚，但是如果要显示更丰富的页眉页脚信息，就需要自己编辑html来作为页眉或页脚的参数传入。 这里的logo.html内容为：
<!DOCTYPE html>
<img src="./images/xxx_logo.jpg" alt="NOBO AUTOMOTIVE" />
footer.html 的内容为：
<!DOCTYPE html>
<div align="right">
<font size=1 color=gray><span>© </span> Copyright
<span id="time"></span>
by </font> <font size=1><strong> XXX TECHNOLOGY CO., LTD</strong> </font>
<div>
<script type="text/javascript">
document.getElementById('time').innerHTML=new Date().toLocaleString();
</script>
这个页脚显示出来的效果就是：
©Copyright Thursday, December 17, 2020 18:12:33 by XXX TECHNOLOGY CO., LTD
即 添加了 转换文档(即发布) 时的日期，时间，星期，以及公司名称等等
为了方面可以将一下内容放在一个目录里面。
html2pdf.bat //转换脚本
logo.html //页眉显示logo
footer.html //页脚信息
images //放置logo图片的目录
最后在使用wkhtmltopdf 的时候也遇到一些问题，比如 表格过长，过宽 都会导致转换出来的pdf转换异常， 经过几番周折，终于找到了解决问题的方法， 在使用typora编辑markdown时，需要将如下内容放入markdown文件的开头，然后再导出html文件
<div>
<style type="text/css">
thead
display: table-row-group;
table td
word-break: break-all;
*
page-break-inside: avoid;
page-break-after: avoid;
page-break-before: avoid;
</style>
</div>
注意： 将这些css放入div标签，只是为了在typora中查看markdown文件的时候，其内容不显示而已。
后续如果再有其他问题，再持续更新。
以上是关于架构师成长之路工具篇：markdown撰写文档的主要内容，如果未能解决你的问题，请参考以下文章