下载安装
- 从vim.org下载 VimWiki。
-
把 vimwiki-N-N.vba.gz 下载到任意目录,用Vim打开,执行
:so %
命令即可。
安装完后,需要一些简单的配置,在_vimrc/.vimrc中添加(这是VimWiki1.2的配置,VimWiki1.1.x的配置略有不同):
let g:vimwiki_list = [{'path':'d:/vimwiki/', \'template_path' : 'd:/vimwiki/template/', \'template_default' : 'default_template', \'template_ext' : '.html', \'path_html': 'd:/vimwiki/html/'} ]
设置了VimWiki的路径,模版文件的路径,默认的模版文件,模版文件的后缀,输出HTML的路径信息。我的一个VimWiki工作目录如下图:
VimWiki语法
VimWiki文件通常以.wiki
为后缀。
标题和目录
通常在wiki文件的页首定义文章标题和目录,如
%title 文章标题-VimWiki插件
%toc 文章目录
在VimWiki生成HTML页面时,将生成 title(标题)和toc(目录)。
标题。通过= 标题 =
的形式定义各级标题,如= h1 =、== h2 ==,最多支持6级标题。可以在任意行按键盘的+
键,就自动添加标题(如果已存在标题,则降低标题级别),按-
键,就自动删除标题(如果已存在标题,则升高标题级别)。
链接(内链和外链)
wiki链接。通过
[[主题]]
的方式,建立新的wiki页。在[[主题]]
上键入回车,就会打开对应的wiki文件,如果没有,则自动创建。
外部链接。通过如
[http://www.berlinix.com 波黎克斯]
的方式,引用外部链接,这种方式的展现效果只显示链接的描述(上例即只显示“波黎克斯”这几个字)。
表格中使用链接的格式为[[link][descr]]
,而不能用通常的[[link|descr]]
格式。
格式化文字段
有几种常见方法:
- 在一行的开始缩进4个字符(所有文字必须在一行)。生成HTML代码<pre>。
-
用
{{{
和}}}
把代码段扩起来(可以有多行)。生成HTML代码<pre>。 - 用"`"(数字键1)前面那个键把文字扩起来(所有文字必须在一行)。生成HTML代码<code>。
修饰文字显示效果
有几种常用方法:
-
用
*
将文字扩起来(*
和前后的文字间要有空格),以加粗方式显示,如*加粗*
的效果为: 加粗 -
用
^
实现文字上标,如x^2^
的效果为:x2 -
用
,,
实现文字下标,如A,,1,,
的效果为:A1
表格
定义表格的语法如:
| HEAD1| HEAD2 | |------+----------| | Vim | Editor | | GCC | Compiler |
_vimrc中的Vimwiki配置
设置.wiki中可用的html标签
我将其配置为所有标签都不支持。因为我的笔记中有一些HTML相关的笔记代码,默认情况下会被浏览器解释为真正的HTML语句。如果你希望在Vimwiki中直接写HTML标签,那可以通过vimwiki_valid_html_tags
选项配置。
let g:vimwiki_valid_html_tags = ''
设置Vimwiki支持的文件后缀
例如在.wiki中refer了一个名为my.cpp
的文件,会被默认扩展为my.cpp.html
,这个选项告诉Vimwiki,对设置了的文件类型不进行扩展。
let g:vimwiki_file_exts = 'c, cpp, wav, txt, h, hpp, zip, sh, awk, ps, pdf'
为VimWiki定义快捷键
nmap <F5> :Vimwiki2HTML<CR> nmap <F6> :VimwikiAll2HTML<CR>
定义了2个快捷键。<F5>是为当前wiki生成HTML(和浏览器刷新键一致),<F10>是为所有wiki生成HTML。
配置多个VimWiki项目
let g:vimwiki_list = [{'path':'d:/vimwiki/'}, {'path':'d:/pwiki'}]
禁用驼峰形式生成wiki页面
指如BerlinWiki这样两个以大写字母开头的单词组合。默认情况下,VimWiki会为驼峰形式的单词,标记为新wiki页面。可以关闭这个选项:
let g:vimwiki_camel_case = 0
自定义的HTML页面
如果生成HTML的目录下有手工hack的html文件,也会被无情的删除,可以通过 g:vimwiki_user_htmls 选项配置用户html文件,不被自动删除。
let g:vimwiki_user_htmls = 'contact.html, canvas-1.html, html.html'
VimWiki技巧
在一个标签上按回车(<Enter>),即可打开新的wiki页。
配置外链浏览器,在一个外链上按回车(<Enter>),即可在浏览器打开目标页面。
退格键(<Backspace>)可以跳回上一个wiki文件。
使用\wr
修改wiki名。有可能修改出错,可以把\wr
后的错误用sed修复,如:
sed -i "s/\[\[\[\[Linux\]\]/\[\[Linux/g" *.wiki
VimWiki 使用体会
我个人使用VimWiki的一些体会。
文件命名
出于编辑效率考虑,我没有在wiki目录下划分目录。区分不同类别的wiki,用文件名完成,例如Linux类别的文档 linux_xxx.wiki,Apache类别的文档 apache_xxx.wiki,如果还有子类,继续用 _ 串联起来。文件名一定要规范,否则等到你需要用脚本批量处理wiki文件时,麻烦就纷至沓来。
文档归类
文件划分的另一个问题是,因为VimWiki创建文件过于方便,所以可能创建很多小文档,其中又没有太多内容(我的wiki就有这个严重毛病,在克服)。最好是把同类知识放入一个文档,直到该文档大得维护/引用不便后,再去拆分。
日期与时间戳
日期。把VimWiki当作知识管理工具,通常无需为文档注明日期,因为需要在一份文档上进行数十,甚至上百次修改(如果你经常更新知识库的话);如果要输出HTML,供人阅读,那最好也通过脚本自动为文档添加日期(最后修改时间)。
写作方法
写作。看到的、实践过的、学习的、经历过的都可以记录在案,供日后快速恢复思路、供人参考之需。有句话说不要在一个地方摔倒两次,那么通过日积月累的写作、归纳,可以在一个小知识点上进行巨大的扩展,打通不同领域的知识。特别是当前人心浮躁,知识碎片过多,通过wiki式的不懈记录,可以积小流而成江海,积跬步而至千里。
VimWiki 可能存在的问题
如果用VimWiki写一篇介绍VimWiki自身的.wiki文档(例如这份文档),就会发现生成的HTML完全走样,因为位于{{{ }}} 中的wiki语句也被解析了,所以要小心避免。
据我的使用经验,VimWiki1.2生成HTML的判断标准是:如果文档有更新,或默认模版有更新,调用 Vimwiki2HTML/VimwikiAll2HTML 会生成新的HTML页面。但如果有多个模版,其他模版修改后,调用 VimwikiAll2HTML 则无效,需要手工删除*.html。
VimWiki的替代品
VimWiki是个非常简单的Wiki系统,如果你嫌它过于简陋,可以尝试其他Wiki系统。
MediaWiki
。维基百科即基于MediaWiki。
Instiki。Instiki用Ruby on Rails写成,作者David H. Hansson也是Ruby on Rails的作者。Instiki支持Textile, Markdown和RDoc三种wiki语法,可将整个wiki网站导出为一个包含静态HTML的ZIP文件,支持Tag和RSS,支持上传图片/文件。Instiki底层使用sqlit作为数据库,因此存储又成了二进制而非文本。