用 Vim、Markdown、Pandoc 与 Markor 搭建一套跨设备的纯文本笔记系统

原创2026-10-02 10:55:391,721 阅读
文章标签:移动开发桌面应用

用 Vim、Markdown、Pandoc 与 Markor 搭建一套跨设备的纯文本笔记系统

本文以 Markor 开源仓库收录的《How I Take Notes With Vim, Markdown, and Pandoc》(作者 James Vaughan,2018 年 5 月)为蓝本,完整还原这套"桌面端 Vim + Vimwiki 编辑、手机端 Markor 管理、Syncthing 同步、Pandoc 生成网页与 PDF"的笔记工作流,并对照 Markor 仓库源码解释其底层实现。读完你就能照着文中的目录结构、index.md 索引页和两份 Makefile,从零搭建一套属于自己的、纯文本优先的跨设备知识库。

一、这套系统的全景

先看作者的 tl;dr,它一句话概括了整套架构:

我在电脑上用 Vim 和 Vimwiki 写 Markdown 笔记,在手机上用 Markor 编辑,用 Syncthing 保持同步,最后用 pandoc 把笔记转成网页和 PDF 来阅读。

拆解开来就是四条明确的分工:

环节 工具 职责
编辑(桌面) Vim + Vimwiki 纯键盘工作流,链接式导航笔记
编辑(移动) Markor 在手机上浏览笔记目录、格式化编辑 Markdown
同步 Syncthing 让同一份笔记文件在多台设备间保持一致
渲染/导出 pandoc 把 Markdown 转成 HTML 网页、PDF 等多种格式

这套系统并非只用于课堂笔记。作者明确列出的笔记对象还包括:读过的书、看过的电影、重要对话、关于人的有趣发现、正在做的项目、菜谱、以及未来的博客文章灵感——本质上是一套个人知识库,而不仅仅是"记课堂笔记的工具"。

二、为什么最终选择"纯文本 + Vim"?

2.1 一段笔记工具的更迭史

作者回顾了自己尝试过的工具:纸笔、Google Docs、Evernote、Simplenote。其中纸笔坚持得最久,但最终被放弃——因为对多数场景而言,"在电脑上检索和格式化笔记"的价值,超过了手写笔记的额外表现力。

Evernote 和 Simplenote 本身是优秀的工具,但作者明确表示:更愿意把笔记保存在文件系统中的普通文件里,这样想怎么组织、修改、解析都行。这正是 Markor 的核心哲学——项目 README 明确写道:"Created files are interoperable with any other plaintext software on any platform"(创建的文件可与任何平台上任何纯文本软件互操作),并且"Compatible with any other plaintext software on any platform -- edit with notepad or vim, filter with grep, convert to PDF or create a zip archive"(可用记事本或 vim 编辑、用 grep 过滤、转成 PDF 或打包成 zip)。

2.2 为什么不是 LaTeX?

作者遇到的第二个问题是编辑器与标记语言的选择。Vim 不是所见即所得(WYSIWYG)编辑器,但作者需要标题、列表、表格、数学公式这类排版能力,因此必须选一种标记语言。起初考虑 LaTeX——因为它熟悉且默认样式漂亮;但发现 pandoc 之后最终选择了 Markdown:用简单的 Markdown 写文档,再通过 pandoc 转成 LaTeX 排版的 PDF、HTML 页面以及一大堆其他格式。

这个选择在移动端同样成立:Markor 的 Markdown 渲染基于 flexmark-java 实现(详见下文"源码级解析"一节),支持的扩展包括表格、任务列表、数学公式(KaTeX)、目录(TOC)等,让手机端也能获得接近桌面的渲染体验。

三、组织方式:一个目录 + 一个索引页

3.1 目录结构

作者把绝大多数笔记放在 ~/Documents/notes 下,按主题或类型分子目录。例如计算机安全课程的笔记放在 ~/Documents/notes/school/cs136。不同笔记之间用标准 Markdown 链接语法互相引用,例如 Computer Science。

这种"根目录 + 分类子目录 + 内部互相链接"的组织方式,恰好对应 Markor 中的 Notebook 概念。仓库 README 的 FAQ 解释:Notebook 就是文件的根目录,Markor 启动时主界面就停留在该目录,允许你浏览文件;根目录位置可自由更换。因此你完全可以把桌面端的 ~/Documents/notes 直接设为 Markor 的 Notebook 目录,两侧看到的目录树就是同一个。

3.2 index.md:整个知识库的"首页"

为了让大量笔记有一个"家",作者维护了一个 index.md。完整内容如下(注意其中使用了 YAML front matter 声明标题与副标题):

---
title: My Knowledge Base
subtitle: >
  This is a collection of things that I know,
  things that I learn,
  and things that I want to remember.
---

## School

- Computer Science
- Math
- Physics

## Technologies

Tips and tricks on different applications and technologies that
I've found myself needing to look up more than once.

#### Languages

- Go
- Python

#### Tools

- Postgres
- MySQL
- SSH
- Git

#### Other

- Linux Audio
- Progressive Web Apps
- Machine Learning

## Misc

- Favorite Film Moments
- <a href="https://link.gitcode.com/i/03a8dd089376ae67dd93ee814853f126" target="_blank">Recipes</a>
- Project Ideas
- Blog Post Ideas
- Music to Listen To
- <a href="https://link.gitcode.com/i/02dc3cb5b8224cc9112d179bc0484069" target="_blank">Book Notes</a>
- <a href="https://link.gitcode.com/i/994d5e19083ad447eb1ada76c26cacda" target="_blank">People</a>
- Quotes I Like

这份文件的三个价值点:

  1. 导航中枢:链接到所有笔记分类,是阅读时的"home base";
  2. 网站首页:将笔记转成静态网站后,它就是现成的主页;
  3. 可被解析的元数据:文件头的 YAML front matter 对 Markor 同样有效——见下文源码解析中 MarkdownTextConverter 对 front matter 的处理。

值得一提的是,这套"索引页 + 子页面互相链接"的思路与 Markor 生态中的 Vimwiki/Zim 工作流完全同源,仓库里收录的另一篇姊妹文章 《Synced plaintext TODO and notes (Vim / Vimwiki, Markor Android, Syncthing, GTD)》 就演示了同一套体系与 todo.txt 任务管理的结合。

四、四种查看笔记的方式

作者配置了多种阅读入口,分别应对"快速查阅"与"大考前复习"两类场景。

4.1 在 Vim 里:Vimwiki 的链接导航

Vimwiki 让在大量 Markdown 笔记间穿梭变得极其容易。作者把光标放在链接上按 Enter 即可跳转到对应笔记——他只使用了 Vimwiki 这一个核心特性(导航),这一点在文末"局限"一节还会再讨论。

4.2 在浏览器里:pandoc + Makefile + rsync

对于零散查阅,作者最常用的其实是浏览器。他用一个 Makefile 把全部 Markdown 笔记批量转成 HTML,再通过 rsync 部署到服务器(置于 HTTP 认证之后)。Makefile 大致如下(缩进已规范为 Makefile 所需的 Tab):

MD_FILES=$(shell find . -name \*.md)
HTML_FILES=$(MD_FILES:.md=.html)
BUILD_HTML_FILES=$(HTML_FILES:%=build/%)

all: $(BUILD_HTML_FILES)

build/assets/%: assets/%
	@mkdir -p $$(dirname $@)
	cp $? $@

build/%.html: %.md template.html
	@mkdir -p $$(dirname $@)
	pandoc -o $@ --template=template.html $<

deploy:
	rsync --recursive --human-readable --delete --info=progress2 \
	       build/* my_server

拆解各条规则的作用:

  • MD_FILES:用 find 递归收集所有 .md 文件,作为输入集合;
  • BUILD_HTML_FILES:把输入文件路径映射到 build/ 目录下对应的 .html 输出;
  • build/assets/%:把图片等静态资源复制进构建目录,保证页面引用不失效;
  • build/%.html:核心转换规则,pandoc -o $@ --template=template.html $< 表示"以 template.html 为模板,把源 Markdown 转为 HTML";
  • deploy:用 rsync 增量、可读进度地把 build/ 内容同步到远程服务器(--delete 会清理远端多余文件)。

作者目前是在笔记改动后手动执行部署,未来计划将其自动化。

Markor 侧的对应能力:桌面端用 pandoc 渲染,手机端则由 Markor 内置转换器负责。README 将其列为核心特性之一——"Convert, preview, and share documents as HTML and PDF"(将文档转换、预览并分享为 HTML 与 PDF)。换句话说,同一份 Markdown 文件,在桌面上交给 pandoc,在手机上交给 Markor,二者产出同构的 HTML/PDF。

4.3 在手机上:Syncthing + Markor

作者用 Syncthing 在电脑与手机之间同步笔记目录,用 Markor 在手机上管理与编辑。他评价 Markor 的优点:浏览笔记目录很方便,内置编辑器对 Markdown 有良好的格式化显示。

关于同步,README 的 FAQ 给出了重要前提:Markor 是并且将一直是一款离线优先的应用,同步工作由外部同步客户端完成;已知可配合的同步客户端包括 BitTorrent Sync、Dropbox、FolderSync、OwnCloud、NextCloud、Seafile、Syncthing、Syncopoli 等,项目官方推荐 Syncthing,并配有专门的配置指南 《Markor: How to synchronize files with Syncthing》。这一"离线优先 + 外部同步"的设计,恰好与本文工作流中"Syncthing 负责搬运、Markor 负责读写"的分工严丝合缝。

4.4 打印:pandoc 生成 PDF + Ghostscript 合并

大考前,作者会为具体课程生成一份合并 PDF 用于复习。以下是软件工程课程的 Makefile 示例:

MD_FILES=about.md 130-final-notes.md general-advice.md requirements.md \
         software-processes.md modeling.md architectural-design.md \
         design-of-components.md software-quality.md \
         configuration-management.md testing.md week-2-discussion.md \
         week-3-discussion.md week-4-discussion.md
PDF_FILES=$(MD_FILES:.md=.pdf)
BUILD_PDF_FILES=$(PDF_FILES:%=build/%)
EXTRA_PDFS=sample-midterm-solutions.pdf

130.pdf: $(BUILD_PDF_FILES)
	gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/default \
	   -dNOPAUSE -dQUIET -dBATCH -dDetectDuplicateImages \
	   -dCompressFonts=true -r150 -sOutputFile=$@ $^ $(EXTRA_PDFS)

build/%.pdf: %.md
	@mkdir -p $$(dirname $@)
	pandoc -V geometry:margin=1in -o $@ $?

这条流水线分两步:

  1. build/%.pdf 规则对每个 .md 调用 pandoc -V geometry:margin=1in -o $@ $?,把单篇笔记转成带 1 英寸页边距的 PDF;
  2. 130.pdf 目标把所有生成的 PDF 交给 Ghostscript(gs)合并成一份总 PDF。其中 $^ 是全部依赖(即所有 build/*.pdf),$(EXTRA_PDFS) 是额外附加的 PDF(如样例期中考试解答)。

作者特别提到"对开卷考试极其好用"——因为他可以把自己允许携带的所有资料提前合并成一份。

五、源码级解析:Markor 如何支撑这套工作流

以上是原文的完整实操内容。下面结合 Markor 仓库源码,看看手机端这一环在底层是如何实现的。

5.1 Markdown 渲染:flexmark-java 与扩展体系

Markor 的 Markdown 转换核心在 MarkdownTextConverter.java。它基于 flexmark-java 构建解析器与渲染器(见 L126-L149),启用了一大组扩展:

  • 表格(TablesExtension)、任务列表(TaskListExtension)、删除线(StrikethroughSubscriptExtension);
  • 自动链接(AutolinkExtension)、Wiki 链接(WikiLinkExtension);
  • 目录(TocExtension / SimTocExtension);
  • 数学公式(FlexmarkKatexExtension,即 KaTeX);
  • YAML front matter(YamlFrontMatterExtension)、Jekyll front matter 与标签(JekyllFrontMatterExtension / JekyllTagExtension);
  • 脚注、emoji、GitLab 风格语法、Admonition(提示块)等。

对笔记场景特别有用的两个细节:

  • 链接中的空格:options.set(Parser.SPACE_IN_LINK_URLS, true) 允许 this 这类含空格的链接写法(L169),并在渲染前自动把空格转成 %20——与原文"用标准 Markdown 链接语法互链笔记"的用法完全兼容;
  • 任务列表的勾选状态:任务列表项被渲染成可勾选的 checkbox(L179-L181),适合"度假打包清单"这类临时勾选场景。

5.2 YAML front matter 与目录(TOC)的自动处理

原文 index.md 开头用了 YAML front matter,这在 Markor 中不是死文本:转换器会解析 front matter(L216-L241),并把允许展示的键渲染成结构化信息块;如果笔记位于 _posts、blog、post 这类博客目录,或用户在设置中开启目录功能,Markor 还会**自动生成目录(TOC)**并插入到文档顶部(L243-L267)。姊妹文章 Pitt 的 Vimwiki/Markor 笔记 中展示的"自动生成的目录"正源于此。

此外,转换器还支持数学公式(检测到 $ 时按设置注入 KaTeX 资源,L269-L277)、代码块语法高亮(检测到 ``` 时启用 prism)以及 Mermaid 图表渲染——这些能力让"课堂笔记、读书笔记、项目文档"都能在手机端获得体面预览。

5.3 语法高亮与测试保障

Markor 的编辑器端通过 MarkdownSyntaxHighlighter.java 实现 Markdown 语法高亮,其中定义了标题、链接、无序列表、有序列表、引用、删除线、代码块等正则模式(L22-L32)。这些模式不是拍脑袋写的,而是有配套测试兜底:例如 MarkdownHighlighterPatternTest.java 以"输入文本 + 期望命中次数"的形式验证了标题、链接、删除线、代码等模式的边界行为(比如 # Hi 与 #Hi 的差异、####### Hi 超出六级标题不命中、链接括号不匹配不命中等),另有多个针对加粗、斜体、列表的专项测试(见 app/src/test/java/net/gsantner/markor/format/markdown/)。这意味着你在手机上编辑的 Markdown,其高亮行为是有明确规格约束的。

5.4 离线优先:与同步工具天然兼容

整套工作流的移动端立足点是"文件在本地":README 的隐私章节明确说明 Markor 默认不联网(除非笔记内容本身引用了外部 URL 资源),文件默认存储在用户可选的本机目录(默认是内部存储的 Documents 目录)。正因如此,Syncthing 这类外部同步工具才能在后台把 ~/Documents/notes 的改动搬到手机上——Markor 只负责读写本地文件,同步完全由 Syncthing 负责,两者互不干扰。

六、这套系统的局限与改进空间

作者直言这套系统"很好但并非完美",并指出两点:

  1. 过度优化的陷阱:他很享受调整 Vim 配置和笔记流程,但"优化"常常花掉的时间比省下的还多——比如为了修正拼写错误词的语法高亮颜色,或纠结生成 PDF 中标题的字体大小,结果错过整段课堂内容。这一点对任何追求工具完美主义的人都适用:工具链稳定后,应把精力放回笔记内容本身。

  2. Vimwiki 使用深度不足:Vimwiki 功能强大,但他只用了"跳转到链接文档"这一项,因此要么换一个更精简的、只包含该功能的插件,要么开始用足 Vimwiki 的更多特性。从仓库生态看,第二条路有现成参考——姊妹文章演示的 Vimwiki 与 todo.txt/GTD 组合(doc/2020-09-26-vimwiki-sync-plaintext-to-do-and-notes-todotxt-markdown.md)就是 Vimwiki 能力的进一步挖掘。

七、小结:从零复现这套系统

最后把整条工作流浓缩为可执行的清单:

  1. 建目录:在电脑上创建 ~/Documents/notes,按学科/类型建子目录;
  2. 写索引:创建 index.md,按文中的结构维护分类链接(可带 YAML front matter,Markor 与 pandoc 都能识别);
  3. 桌面编辑:Vim + Vimwiki,利用 Enter 键在笔记链接间跳转;
  4. 手机接入:安装 Markor,把 Notebook 根目录指向同步中的同一目录,手机即可浏览、编辑、渲染同一批 .md 文件;
  5. 同步:用 Syncthing 双向同步笔记本目录(配置细节可参考 仓库内 Syncthing 指南);
  6. 导出:照抄文中的两份 Makefile——一份用 pandoc + rsync 把笔记发布成带密码保护的静态网站,另一份用 pandoc + Ghostscript 把课程笔记合并成复习用 PDF;
  7. 约束自己:把"优化工具链"的时间预算设好,把剩余精力留给笔记内容本身。

这套系统的本质,是把"笔记"还原为"普通的纯文本文件",从而让编辑、同步、渲染、归档各自交给最擅长的工具。Vim 负责高效输入,Syncthing 负责搬运,pandoc 负责输出,而 Markor 则把同一批文件在 Android 端重新激活——这正是 Markor 项目"与任何平台上任何纯文本软件互操作"的设计初衷。

登录后查看全文
markor