标签：md markdown vim html 文档 导航 Debian
本贴介绍了在debian中如何使用vim撰写markdown文档。
一、Retext
首先上互联网查阅一下在linux下用得最多的markdown写作软件，从软件仓库安装了Retext，使用了一下，总的来说很方便，有实时预览窗口、按键后预览、导出为html文档等；输入公式的话，也有说明，需要加载Mathjax，预览的话，要启用webKit渲染（转换成html后自然由浏览器负责）等；代码高亮也行，需要加载highlite插件。就有一个不足，左侧导航栏显示的是目录结构，不是文档结构，文章比较长时定位不方便，往往需要从头向后翻页。
二、html文档中添加左侧导航栏
在Retext中添加左侧导航栏是不现实的，帮助文档中没有说明。但通过网上搜索发现输出的html文档可以增加导航栏，有多种方法，有的是把md文档粘贴到html样板文档里，有的是把md文档粘贴到样板文件夹中。在博客园有一博文将markdown (md)文件转换成带侧边栏目录（toc）的html文件，提供一个python脚本(md_conv.py)，它是基于python-markdown库的，自动完成md文档嵌入到带左侧导航栏的html样板文档。这正是自己需要的。首先用pip install markdown安装python-markdown，然后使用脚本md_conv.py处理自己的md文档memo.md，命令如下：
python3 md_conv.py memo.md
发现输出的html中表格、公式和代码块都还是markdown文本。记得Retext中是需要添加这些功能的扩展模块，这个md_conv.py也应该是可以扩展的，其中下列代码就是在创建实例时引入扩展的：
md = markdown.Markdown(extensions=['tables','toc','fenced_code','codehilite','mdx_math'], output_format="html5")
到python-markdown网站 了解了一下可用扩展（extension）的列表，把相关的"Entry Point"名称填入就行。
1、关于表格线
生成的html表格没有框线，需要在<head>里添加css样式：
table, th, td {border: 1px solid; border-collapse: collapse;}
其中border属性控制线宽，border-collapse让表格框线和单元格框线合而为一。
2、代码块语法高亮
包含了highlite扩展还不行，代码没有出现语法高亮，还需要提供相应的css文件，用下列命令可以生成：
pygmentize -S default -f html -a .codehilite > md_conv-code-highlight-styles.css
其中pygmentize是软件包python3-pygments中的命令,需要安装：
sudo apt install python3-pygments
在html文档中引用这个css就行：
<link href="./md_conv-code-highlight-styles.css" rel="stylesheet" type="text/css" />
需要将这个css文档与html文档放在同一目录，这样它就可以为多个html文档服务而不需要制作很多拷贝了。
3、数学公式
最后一个'mdx_math'就是数学公式的扩展，不在这个标准的扩展列表中，而是在extra列表中，md_conv.py是python脚本，选用python版的数学扩展是再自然不过的。
(1)安装
从python库PyPI安装：
$ pip install python-markdown-math
(2)引用
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js">
</script>
其中@2表示版本2。使用时要注意，默认行内公式标记$ ... $ 不起作用，必须用\( ... \)。一开始即使使用\(标记也显示不出公式，文本文字也不见了，后来观察了一下Retext生成的html文档，发现引用的是MathJax3.0而不是2.0，初始化代码也不同。将初始化代码复制粘贴到md_conv.py中，将MathJax3.0相应的js库链接也粘贴到html样版代码中，代码如下：
<script>
MathJax = {
options: {
renderActions: {
find: [10, function (doc) {
for (const node of document.querySelectorAll('script[type^="math/tex"]')) {
const display = !!node.type.match(/; *mode=display/);
const math = new doc.options.MathItem(node.textContent, doc.inputJax[0], display);
const text = document.createTextNode('');
node.parentNode.replaceChild(text, node);
math.start = {node: text, delim: '', n: 0};
math.end = {node: text, delim: '', n: 0};
doc.math.push(math);
}
} , '']
}
}
};
</script>
<script type="text/javascript"
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js" async>
</script>
再进行转换，公式就出来了。
4、关于标题编号
md_conv.py脚本如果不指定--no-number参数，就会给标题添加1 1.1 1.1.1等编号。这里不需要这个编号，因此转换时需要加上这个参数。
5、关于导航栏标题的项目符号与间距
导航栏标题有项目符号，可以使用css中的list-style-type:none加以消除。
导航栏各级标题之间默认缩进距离较大，只修改左缩进，设置margin-left为10px，其它为默认值0，这样比较紧凑。css代码如下，存放在md_conv.py的html样本代码中，选择器选择.toc ul，表示是类toc中的ul，不影响正文中的ul的样式：
.toc ul {
margin-left: 10px;
list-style-type:none;
}
三、带导航栏的vim
html中带导航栏只给阅读该文档带来方便，并没有给写作带来方便。不知emacs会不会带这种导航栏，用命令apt search emacs markdown进行了搜索，意外发现有个软件包的说明里包含了"two panel,outline plugin for vim"几个单词，感觉这就是我所需要的，用命令sudo apt install vim-voom安装后查看其帮助文件，果然是给vim提供导航栏功能的插件。既然vim有导航栏功能了，就不再去关心emacs了。
1、voom插件的启用
在vim中通过冒号命令启用：
:Voom pandoc
"pandoc"是模式参数，对应不同的类似markdown的文档格式，选用markdown时，发现代码块里的#也处理成了标题，导航栏多了很多垃圾，使用pandoc模式时没有这种情况，因此，以后使用pandoc模式。
2、导航栏与文档窗口的切换
导航栏窗口与文档窗口的切换使用tab键，在导航栏可以使用方向键选择所需标题，按回车键或空格键完成窗口切换与光标定位。当某标题的右侧出现数字时，表示该标题有小标题，只是被收拢了，按向右键或向左键可以控制收拢和展开。
四、首行缩进
中文段落总有首行缩进的习惯，这个效果可以通过css指令来实现：
p { text-indent: 30px;}
这样，生成的段落都会有一个30px的缩进，差不多是2个默认字符的宽度。
五、调整vim行间距
vim中默认的行间距略显窄，看着吃力。但vim是典型的控制台（终端）程序，本身是不能修改行与行之间的间距的，但在GNOME环境可以通过“配置文件首选项”修改gnome-terminal的行间距就可以达到改变vim行间距的目的。行间距改为1.3倍就可以了。
六、小结
在Debian GNOME图形桌面中，用vim+voom插件进行markdown写作，带左侧导航条；用md_conv.py进行文档转换，通过插件支持了表格、数学公式、代码语法高亮显示，通过定制html模板美化生成文档，如显示导航栏、去除导航栏项目符号、段落首行缩进等。
标签：md,markdown,vim,html,文档,导航,Debian 来源： https://www.cnblogs.com/zhenggennj/p/16272404.html
本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享； 2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关； 3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关； 4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除； 5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。