Last update: 2022-08-06 23:33:32

# vimwiki 插件简介、安装和一些设置

在 vimwiki 里，所有的入口集中在指定的项目根目录下的 index.md 文档里。也就是要构 建的整个笔记系统（随便管它叫什么），index.md 可以成为它的整体框架以及各个主题的 索引。从这里可以去到各个主题，从各个主题的索引去到对应的内容，也可以从一个内容 去到另一个内容，内容可以是本地文档内/文档间，这完全取决于如何构建内容之间的连接。

vimwiki 提供了必要的基础。但通常我们要写的文档并不是纯文本 (plain text) 而是带有 修饰语法的文本，比如 markdown, Tex/Latex 格式的文档。这两者的区别在于，前者是“ 所见即所得”，意思就是你写出来的内容和最后呈现的内容一模一样；后者则更像是写代码， 最后呈现出来的和所写的内容一致（但大部分时候不会一模一样），有人称之为 “所想即所得”，听起来有点玄乎。直接用 plain text 格式不就完了，折腾这些干嘛？遗憾 的是，只要你想要写一些复杂一点的数学公式（求导的链式法则），那么，没有专门的编辑 器的话，最快能够得到规范的数学公式的方法就是 – 手写。教科书内那些数学公式的呈现 效果基本都来自排版系统工具（Tex/Latex等）的支持。

如果工作的内容涉及到较多的高等数学，并想自己编写的日志博客得到类似教科书式的数学 公式呈现，markdown 文档是相当友好的文本格式，而从 markdown 到最终效果的呈现之间， 需要我们作一些额外配置。

现在我只需要用 mardown 格式编写内容，在本地链接的文字上敲击回车键(命令模式下)， 就可以打开这个本地链接的内容文档，然后编辑内容或者发呆或者别的什么，敲击 Delete 键(命令模式下)回到之前跳转来的地方；当然也可以设置和使用其他组合键来去到其他地 方。在每个地方，都可以用浏览器展示当前文档的内容的最终呈现效果，比如使用默认的 <leader>+w+h+h 快捷键就能在你的默认浏览器展示当前文档的内容，数学公式正是课本 上的那种它该有的样子，也可以像浏览百科网页时那样，自由跳转，来去自如。

闲话少叙，直接上手。

## 安装 vimwiki 插件

(使用管理插件的 Vim-Plug 插件来安装和管理)

将下面的语句加入你自己的 vim 配置文件中，

Plug 'vimwiki/vimwiki'

然后运行命令 :PlugInstall

如果你还不清楚这是什么意思，搜索: vimrc 或者 点击这里

## 配置 vimwiki 插件

• markdwon 格式

vimwiki 默认使用 .wiki 格式，但这个格式的语法没有 markdown 语法使用的广泛和普遍, 所以我个人是更倾向于使用 markdown 格式来编写文档。可以按照下面的做法进行相应配置： 将下面的语句加入 .vimrc:

let g:vimwiki_ext2syntax={'.md': 'markdown', '.markdown': 'markdown', '.mdown': 'markdown', '.rmd': 'markdown'}

这是几个较为常见的 markdown 文档的后缀，最后一种 rmd 是 Rmardown 格式后缀。

• 多个 index.md 文档

前面提到过，index.md 是 vimwiki 的默认入口，类似于一本书的主目录，或者电子菜单。 通常我们需要多个菜单，每个主题配一个菜单，从而使得内容更精简和自洽，而不是所有 的内容全都汇集并拥挤在同一个地方。在顶级菜单，只需要给出到各个主题的链接即可。 就像大饭店的电子菜单，客人对川菜感兴趣就点击“川菜”的目录即可，但没有必要将八大 菜系所有菜名全都拥挤到一个主菜单上。
同上，将下面的语句加入到 .vimrc
(不要直接复制粘贴，然后指望它就马上见效 🙄 因为你的目录不会/也不需要和我的相同):

  let g:vimwiki_list = [
      \ {'path': '~/VimWiki', 'syntax': 'markdown', 'ext': '.md', 'index': 'index',
      \  'path_html': '~/VimwikiHtml',
      \  'template_ext': '.html',
      \  'template_default':'markdown',
      \  'template_path': '~/VimWiki/template/',
      \  'custom_wiki2html': '~/VimWiki/wiki2html.sh',
      \ },
      \ {'path': '~/VimWiki/LinuxTools', 'syntax': 'markdown', 'ext': '.md'},
      \ {'path': '~/VimWiki/LinuxTools/vim8', 'syntax': 'markdown', 'ext': '.md'},
      \ {'path': '~/VimWiki/LinuxTools/CLIs', 'syntax': 'markdown', 'ext': '.md'},
      \ {'path': '~/VimWiki/Programing', 'syntax': 'markdown', 'ext': '.md'},
      \ {'path': '~/VimWiki/Programing/Julia', 'syntax': 'markdown', 'ext': '.md'},
      \ {'path': '~/VimWiki/Programing/Latex', 'syntax': 'markdown', 'ext': '.md'},
      \ {'path': '~/VimWiki/Programing/Python', 'syntax': 'markdown', 'ext': '.md'},
      \ {'path': '~/VimWiki/Programing/ShellScripts', 'syntax': 'markdown', 'ext': '.md'},
      \ ]

在上面这个例子中，每一个花括号的内容其实就是对应一个主题的菜单 (index.md)，根据 vimwiki 的默认快捷键, 比如， 2<leader>ww 就会直接打开 ~/Vimwiki/LinuxTools/index.md 这个文件。 那么，和以上的设置对应的目录结构是怎么样的呢？以下就是我个人 vimwiki 目录结构 (使用命令 tree -L 2):

.
├── index.md
├── LinuxTools
│   ├── commonCommandLines.md
│   ├── images
│   ├── index.md
│   ├── jupyterWithDSKernels.md
│   ├── linux_oracle_client_sqlplus_install_and_connection_setup.md
│   ├── linux_sqlserver_sqlcmd_install_and_connection_setup.md
│   ├── newBashConfig.md
│   ├── python_packages_management.md
│   ├── tmux.md
│   ├── vim8.md
│   └── vimwiki.md
├── mathjax
│   ├── bower.json
│   ├── composer.json
│   ├── CONTRIBUTING.md
│   ├── es5
│   ├── LICENSE
│   ├── package.json
│   └── README.md
├── myvimwikidir.txt
├── Programming
│   ├── index.md
│   ├── Julia
│   ├── Latex
│   ├── Python
│   └── ShellScripts
├── Session.vim
├── template
│   ├── default.html
│   └── markdown.html
└── wiki2html.sh

如前所述，根目录的 index.md 是顶级主菜单，从这个文件内跳转到各个子主题。比如， 我个人感兴趣的、一直在学习的3大主题分别是：机器学习（未列出），编程和Linux工具。 而在 Programming 这个目录下的 index.md 就是这个主题的主菜单，显然，这个主题 下还有‘Julia’，‘Latex’，‘Python’，‘ShellScripts’等几个内容。不用说，还可以设计 更细分的内容。每个主题都足够我喝上几壶的了 🍻 。毕竟，谁又说了构建比较完整的 知识体系是一朝一夕能完成的呢？正所谓，志不强者智不达。

而 mathjax 目录，正是想要展现数学公式效果所依赖的本地包，接下来就讲这个的配置。

## 数学公式的呈现

vimwiki2html 命令和 “mathjax” 目录

vimwiki 自带了一个 vimwiki2html 命令，顾名思义，就是把 mardown/wiki 格式的源 文档转换成 html 格式的文档。但这个命令并不支持数学公式的渲染，得改造。这正是 mathjax 闪亮登场的地方。已经有人把 vimwiki2html 命令所依赖的脚本作了相应的升级版， 它能将 markdown 文件转换为 html 文件，并支持数学公式的渲染。有些人走的更远 但他们均假设没有所谓的什么“外网”访问限制云云。所以，还需要一点折中操作，那就是 ‘本地化’。先哲说‘山不过来，我走过去’。网络时代刚好相反，既然访问不到，那就把它 复制回来（基本前提是开源，嗯，伟大的开源）。

所谓本地化，就是：1）把 mathjax 复制到本地；2）配置 vimwiki 的命令脚本找到它。 以下是具体操作：

1. 在 vimwiki 的根目录下，执行以下命令：

git clone https://github.com/mathjax/MathJax.git mathjax`

2. 下载并更改 wiki2html.sh 文件的以下内容 (# 号开头的语句是被注释掉的原文，以备参考):

    # HAS_MATH=$(grep -o "\$\$.\+\$\$" "$INPUT")
    # if [ ! -z "$HAS_MATH" ]; then
    #     MATH="--mathjax=https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
    # else
    #     MATH=""
    # fi

    HAS_MATH=$(grep -o "\$\$*\+\$\$" "$INPUT")
    # # load mathjax from local copy (in case the CDN not work)
    if [ -n "$HAS_MATH" ]; then
        MATH="--mathjax=path2your-mathjax/es5/tex-chtml.js?config=TeX-AMS-MML_HTMLorMML"
    else
        MATH=""
    fi

注意：“path2your-mathjax” 应该修改成你自己的路径， 比如我的路径是这样的：’/home/myacct/VimWiki/mathjax/es5/'

我不太懂 html，我在这里的诉求就是能让转换后的 html 文档正常显示数学公式。 但后来发现，要实现这个目标，其实不一定非得先转换成 html 文件。

# markdown 文档的即时展示: vim-instant-markdown

前面说过，大部分的 markdown 并非“所见即所得”，但如果一个人的欲望正常，通常都想 要看看正在写的内容到底是什么显示效果，毕竟，早发现早治疗嘛（一气呵成的爽文自然 是有，但我更相信优秀的作品通常是修改出来的）。当然，早就有人把这种正常不过的 需求实现并共享了，那就是： vim instant markdown 这也是一个 Vim 的插件，具体的安装和配置也简便，直接根据其 readme 文件进行即可。

但其实“每改一个字就刷新一次”和“写完了所有内容才看上一眼最终效果”一样不甚妥贴， 前者使人分心，后者使人担心。因此，当想要检查某个段落（尤其是包含许多数学公式 的段落）的呈现效果时，调用命令 InstantMarkdwonPreview ，停用则 InstantMarkdwonStop。 我很喜欢这种快速反应，有仇就报，当场就报；知错就改，善莫大焉。 但如果觉得白纸黑字的预览网页版面过于朴素不够滋味，那么，可能你需要的是一个能够自定义的网页。

# markdown 文档的即时展示: jekyll-site

vim-instant-markdown 展示的就是文档的呈现内容，也仅仅就是内容而已。如果想要 更多，那么，备选方案就是静态网站生成器（如jekyll)， 顾名思义，就是这玩意儿直接给你打包生成网站需要的一揽子部件。 （网站意味着高度定制的自由，是不是听着就觉得开心？如果你够耐心看到这里，我就 估摸着你也应该也是个爱折腾的人，爱在机器上捣鼓各种工具的人想必也知道，所谓的 “高度定制”的另一个说法大约是说：来呀，折腾呀，快活呀）。

你知道吗？从 vimwiki 的编辑系统到 jekyll 博客网页，只需要一个命令：:Postit

当然了，这明显属于广告用语，和‘一天学会python，七天掌握机器学习’之类差不多。

俗语有云：“前端一分钟，后端十年功”。Postit 命令需要一些基础来支撑：

command Postit :execute "w!" . "Path_to_jekyllsite_root/_posts/" . strftime("%Y-%m-%d-") . expand("%:t")

这语句要写在 .vimrc 文件里，这个实际上是设置 vim 命令。

注: 这个命令的实际意思是：将当前编辑的文件以 jekyll 的 post 文件的所要求格式 进行命名，并保存到你的 jekyll 项目的 _post/ 目录下。

因为 jekyll 的 post 全部要求以“年-月-日-”作为文件名前缀 (比如： “2022-02-02-好多二.md”)。命令中的 “.” 是 viml 语法中 “concatenate” 的意思。

虽然谈不上难以忍受，但我个人不是很理解这种硬编码，文件命名格式为何非如此不可？ 是bug还是feature，那就见仁见智了。我听说还有一个静态网站生成器名叫 Hugo 的，不知其手艺如何 …

刚开始使用 vimwiki 时，也是不停的摸索，数学公式的显示一直是个头疼的问题，毕竟， 从“歪果仁”那里借鉴来的默认配置需要能访问外网，而这个想必不是我们能够默认得了的， 只能先忍着那些令人不快的如同乱码的 latex 语句挂在页面上， （尤其是，当你明明知道这些公式本可以优雅的展示，却不能够时，不快就变成了愤怒）。

没有像作为新手时在不同的 Linux 发行版跳来跳去那般，我知道 vimwiki 就是我的菜， 以前使用 vimwiki 过程碰上的各种“暂时”的没有解决的问题，开始变得令人不能忍受， 特别是平时浏览其他网页时每每看到人家的的数学公式又多又靓，那简直就是一场侮辱。 我走了这么远，就差那么最后一步，我心不甘。所以我就折腾，一天，两天，三天 … 我是贪婪的人，无法放弃一步之遥的诱惑，幸运的是我还是折腾到了我想要的“更多”。

是的，距离太远可能直接放弃，而一步之遥最是销魂 😂

其实，该庆幸的是我碰上的问题早就有人先碰上也先解决了，我只是找到了这个方法， 应该说是‘搜索’到了这个方法，并作了必要的调整。‘闻道有先后’的基础就是分享， 对于这些解决了实际问题的人，很是感激他们的分享，没有分享，大家的日子不会好过。