1. 从零开始搭个人知识库为什么我最终选了“纯文本静态站点”这条路这事儿得从三年前说起。当时我的电脑里有四处散落的笔记手机备忘录里堆着临时想法公司电脑桌面放着项目文档家里笔记本存着各种教程收藏还有几个网盘文件夹里面是历年攒下来的资料截图。每次想找一个东西得先在脑子里回忆“当时记在哪儿了”然后逐个翻找折腾十分钟还不一定找得到。最崩溃的一次要找一个去年写过的方案模板翻遍了五个地方都没找到最后发现它安静地躺在某个压缩包的深处。后来我开始研究个人知识库的搭建方案试过Notion、语雀、印象笔记也试过本地部署的Trilium和思源笔记。折腾一圈下来我反而选择了最“笨”的一条路Markdown纯文本 Git管理 静态站点生成器。今天这篇文章就把这套方案的完整思路、具体操作和我踩过的坑都写出来给同样被信息管理困扰的朋友一个参考。这套方案适合谁如果你像我一样有大量文字笔记、技术文档、文章草稿需要长期管理并且希望这些内容脱离开特定软件平台、随时可以用任何设备访问那么纯文本方案大概率比商业笔记软件更适合你。它有学习门槛但一旦跑通体验非常香。2. 整体设计思路别急着选工具先想清楚要解决什么问题2.1 个人知识库的本质是什么我见过很多人搭知识库第一步就是跑去注册各种软件账号然后开始往里面塞内容。但搭了几个月后发现资料是存了不少真正用的时候还是找不到知识库变成了“数字垃圾堆”。个人知识库的本质不是“存储”而是“检索”和“连接”。存储只是第一步更重要的是当你需要某个信息时能在最短时间内把它找出来并且能看到它和其他信息之间的关联。我决定用纯文本方案核心原因有三个第一纯文本是永恒格式。TXT和Markdown文件半个世纪后依然能打开但某个商业软件的专属格式可能连官方自己都会在新版本里放弃兼容。我吃过这个亏——几年前在一款笔记软件里写了大量内容后来软件停止维护导出的数据格式乱七八糟损失惨重。第二纯文本是极简格式。不依赖数据库不依赖网络服务一个文件夹加几个TXT文件备份就是拷贝文件夹传输就是压缩打包没有任何技术壁垒。第三纯文本是通用格式。几乎所有的编辑器、代码工具、转换程序都原生支持它。这意味着你可以在任何设备上、用任何工具来读写自己的知识库完全不被某个软件绑架。2.2 为什么选用“观察-判断-行动”的渐进式整理法很多人搭知识库容易陷入一个误区一上来就设计一套复杂的分类体系预设十几个文件夹和几十个标签结果真正用的时候发现内容根本装不进这些预设的格子于是大量内容被随手丢进“未分类”整个体系慢慢就废了。我采用的思路是反向的不预设结构先让内容自然生长然后定期观察内容的分布规律再做结构调整。具体来说就是三条原则新内容永远先进“收件箱”不做即时分类每周花十五分钟处理收件箱给内容打标签或归档每月做一次整体审视根据内容增长趋势调整目录结构这套方法的好处是知识库的结构是从你自己的使用习惯里长出来的而不是从别人的理论里抄来的。用了半年后我发现自己关于“写作”的内容占了很大比例于是单独拆出了一个“写作”目录而原本预设的“项目管理”目录几乎没什么内容就把它合并进了“职场”目录下。这种动态调整能力纸笔时代很难做到但纯文本体系里就是改个文件名、拖个文件夹那么简单。2.3 方案选型对比为什么不是Notion为什么不是Wiki.js我并不是全盘否定商业笔记软件。如果你是团队协作或者你特别喜欢图形化界面、数据库视图这些功能Notion这类工具确实有它的优势。但对我个人的使用场景来说它的短板也很明显对比维度Notion类商业软件纯文本静态站点方案数据所有权存储在服务商服务器导出格式受限文件完全在本机格式全开放离线访问部分功能需联网离线体验一般Markdown文件纯本地离线完全可用长期可维护性依赖厂商持续运营格式本身永久可读灵活性视图和模板受限于软件设计任何文本编辑器都能读写学习门槛工具本身功能繁多需学习工具上手快但需要一点命令行基础Wiki.js这类自建Wiki系统我也考虑过。它功能很强但必须跑在一台服务器上还要维护数据库和Web服务对个人用户来说运维成本实在太高了。有一次我为了升级系统版本折腾了整整一个周末最后还搞坏了数据库从那以后我彻底放弃了“为了管理笔记还得先当个运维工程师”的路线。纯文本方案真正需要的工具其实非常轻量一个编辑器我用VS Code你也可以用Typora或者Vim一个版本管理工具Git一个可选的内容发布工具我用了MkDocs。硬件上一台普通电脑就完全够用了。3. 核心配置与目录结构设计让文件自己会说话3.1 目录结构按照“工作流”而不是“学科分类”来组织知识库目录结构设计是决定整个系统好不好用的关键。我见过有人按照“编程-设计-写作-营销”这种学科分类来组织也见过按“工作-A-项目B-项目C”这种方式搞的但用起来都别扭——因为很多内容天然就是跨领域的强行归类只会增加寻找成本。经过反复试错我的目录结构设计逻辑是靠近使用场景而不是靠近学科分类。也就是说想一想你平时是怎么用这些知识的顺着使用路径来组织文件。目前我的知识库根目录长这样knowledge-base/ ├── 0-inbox/ # 收件箱所有新内容先进这里 ├── 1-projects/ # 进行中的项目相关笔记 ├── 2-areas/ # 长期关注的领域健康、理财、家庭等 ├── 3-resources/ # 参考资料、教程、书摘等 ├── 4-archive/ # 已完成或不再活跃的内容 ├── 5-daily/ # 日记、日志、时间线记录 ├── templates/ # 模板文件读书笔记、会议纪要等 └── assets/ # 图片、附件等非文本资源看明白了吧这个结构借鉴了著名的时间管理方法GTDGetting Things Done的思路用“项目-领域-资源-归档”来替代传统的“科目分类”。其中最有用的设计是0-inbox收件箱所有临时想到的念头、刚看到的文章片段、随手记的点子统一扔进去不需要当时就决定放哪儿这个决定可以留到每周的整理时间再做。实际使用中这个设计的价值怎么强调都不过分。以前用其他笔记软件时我经常在“新建一条笔记”时卡壳——标题写什么放哪个文件夹加什么标签这些决策成本会实实在在打击你记东西的积极性。现在好了哪怕只是记一句“记得买牙膏”也是按快捷键新建文件丢进收件箱三秒钟搞定。3.2 文件名规范机器可读人也可读文件名是很多人忽略的细节但实际上它对搜索效率的影响非常大。想象一下你的知识库里有一个文件叫笔记1.md另一个叫新建文档3.md一年后你还能记得里面写的是什么吗我采用的规范是“日期 关键词”的组合方式2024-12-01-搭建个人知识库方案.md 2024-12-05-阅读笔记纳瓦尔宝典.md 2024-12-08-家庭网络改造计划.md这个格式有几个好处。第一按文件名排序时同一个主题的内容会自动按时间聚在一起第二只要瞄一眼文件名就能大致知道这篇笔记的内容第三用系统自带的文件搜索工具就能快速定位不需要额外软件。另外我建议文件名里不要使用空格。用-或_来连接单词或词组。原因很实际某些命令行工具和软件对空格的处理比较麻烦而中划线在绝大多数场景下不会引起问题。这一点细节看似无关紧要但等你需要在终端里批量操作文件时就知道多省心了。3.3 标签系统别搞一二十个标签五个以内最合适标签是比目录更灵活的内容关联方式。目录是“物理上”把文件放进某个抽屉标签是在“逻辑上”给文件加上多个属性。比如一篇关于“Python爬虫”的笔记放在“编程”目录下但它同时可以被打上“自动化”“数据分析”的标签这样从多个维度都能找到它。但问题在于标签系统很容易失控。我用过的笔记软件里有人给笔记打了十几个标签结果每个标签下面只有一两篇笔记标签彻底失去了导航价值。我的做法是二级标签制第一级是领域标签控制在大约五个以内第二级是状态标签标明内容所处的阶段。下面是我目前全库在用的全部标签领域标签#编程、#写作、#理财、#生活、#健康状态标签#待处理、#进行中、#已完成、#常青领域标签帮你从内容维度筛选状态标签帮你从处理进度维度筛选。两者结合已经覆盖了我日常90%以上的查找需求。而且标签和目录可以共存两者并不冲突。目录解决“这个东西归在哪里”的问题标签解决“我用什么关键词能找到它”的问题。一个是归纳一个是索引。3.4 模板系统把重复劳动变成一次配置有了模板记笔记就能从“每天写一份新的”变成“填一份固定的表”。这听起来很无聊但实际上能显著降低记笔记的心理门槛。目前我的知识库里有这么几个核心模板读书笔记模板书籍信息书名、作者、出版年份 核心观点摘录 个人思考批注 行动清单。这个模板的价值在于读完一本书后我能快速生成一份结构化笔记而不是对着书发半天呆不知道记什么。项目复盘模板项目背景 目标回顾 执行过程 结果对比 经验教训 行动项。团队开会做复盘时我直接打开这个模板边听边记最后整理出来就是一份完整的复盘报告。会议纪要模板会议主题 参与人 时间 关键讨论点 决议事项 待办清单责任人截止时间。用这个模板我记录一次会议只需要十分钟但会后要追溯某件事是谁负责的一秒钟就能找到。模板文件统一放在templates/目录下每个模板就是一个Markdown文件。新建笔记时复制对应模板文件改一下标题和日期即可开工。4. 实操搭建全过程从文件夹到可检索知识库4.1 基础环境准备编辑器、Git与文本工具链开始动手之前需要把工具链准备好。我的参考配置如下你可以根据自己情况调整Markdown编辑器首选VS Code Markdown插件免费、跨平台、插件生态丰富。如果你不习惯代码编辑器的手感可以用Typora它所见即所得特别适合纯写作场景。两个都行核心是找到自己用得顺手的工具。Git版本管理Git是这套方案里的隐形英雄。每修改一篇笔记git commit一次就相当于给整个知识库拍了一次快照。万一误删了文件、写错了内容还能回滚。平时我每次整理完收件箱都会顺手执行一次提交不到十秒钟的操作换来的却是历史记录永久的保留。由于Git对中文文件名的支持在旧版本上存在一些小问题建议把Git升级到最新版本。同时将git config core.quotepath false设置好否则中文文件名会在Git状态输出里显示成转义字符看着非常不舒服。本地全文搜索VS Code自带的搜索功能已经相当快支持正则表达式遍历整个知识库搜索某个关键词通常一秒内出结果。这条我用得比任何标签系统都频繁——搜索才是知识库的第一生产力工具。4.2 基于MkDocs搭建静态站点如果你的知识库只是给自己看到上一步已经够了。但我的需求比较特殊有些整理好的笔记想分享给朋友或团队同事看这就需要把Markdown文件发布成一个可以在浏览器里阅读的网站形式。这里我用的是MkDocs一个基于Python的静态站点生成器。它的特点是不需要数据库不需要服务器端动态解析预先将Markdown文件渲染成HTML文件发布到任意Nginx服务或代码托管平台的静态页面服务上即可。安装过程很简单需要本机装好Python环境pip install mkdocs mkdocs new my-project cd my-project核心配置在mkdocs.yml文件里site_name: 我的知识库 theme: name: material # 我用的是Material主题颜值和功能都比较在线 nav: - 首页: index.md - 编程: 1-projects/编程/ - 写作: 2-areas/写作/ - 资源: 3-resources/之后在知识库目录里执行mkdocs serve # 本地预览 mkdocs build # 生成静态网站这样就会生成一个site/目录里面全部是HTML文件。由于图片等资源引用的路径是相对路径所以整个site/文件夹拷贝到任何静态托管平台上就能直接访问非常方便。4.3 我的“双链”替代方案用“反向链接索引”实现内容关联我明白纯文本方案在“双链”功能上比Roam Research这类专用笔记软件弱不少——也就是笔记之间可以通过[[笔记名]]的方式进行双向关联。纯文本没有内置的“双链”支持但这个问题有很好的替代方案。我的做法是在每篇笔记的末尾手动维护一个“相关笔记”列表。## 相关笔记 - [[2024-12-01-搭建个人知识库方案]] - [[2024-12-05-阅读笔记纳瓦尔宝典]] - [[2024-12-08-家庭网络改造计划]]VS Code有一个名为Foam的插件可以扫描整个工作区把[[链接]]语法转换为可跳转的链接并在侧边栏显示反向链接列表。经过这样配置后从功能体验上来说已经非常接近Roam Research了——而且数据依然是纯文本不依赖任何专有数据库。4.4 手机端访问方案随时随地补充内容纯文本方案最大的短板在手机端在手机上修改Markdown文件毕竟不如打开一个App方便。我的解决方案分两层简单场景随手记录用手机的备忘录写几句话之后每周统一整理时复制粘贴到收件箱里对应的Markdown文件。这个方法看起来笨但实际使用中非常高效因为“快速捕获”发生在手机里而“整理归档”发生在电脑上这个分工是合理的。正经编辑场景我用的是Obsidian的移动端App支持本地Markdown仓库同步。Obsidian本身也是一个Markdown笔记软件但它同时支持纯文本模式直接打开你电脑上的知识库文件夹就能编辑。配合第三方同步工具比如坚果云或Sxxn这类工具都能用自己选合规矩的即可实现手机和电脑的文件同步。这样一来地铁上用手机写完一篇笔记的草稿回家打开电脑已经是最新版本了。安全提醒一句不要图省事把整个知识库扔进某个只提供“公开分享”的网盘上。个人知识库在某种程度上是很私密的数据建议用带加密功能的同步方案至少也要确认网盘的隐私设置靠得住。5. 常见问题排查与避坑实录5.1 为什么我的图片有时候显示不出来用Markdown插入图片非常简单但很多人都会遇到图片不显示的问题。根据我的经验90%的原因是路径写错了。特别需要注意Markdown文件的相对路径是基于当前文件所在位置来解析的不是基于知识库根目录。比如你的笔记文件在2-areas/写作/目录下图片在assets/目录下那正确的引用路径应该是../表示回到上级目录上面的写法需要先上两级才能到根目录。我自己的经验是尽量统一用根目录下的assets/文件夹来统一存放图片然后在笔记中使用绝对路径以/assets/xxx.png的方式来引用。虽然本地预览时需要额外配置一下但发布到网站上的时候兼容性最好。另外一个小坑文件名里的中文和空格在部分web服务器上会变成乱码或者404。保险的做法是图片文件名改成拼音或英文比如jia-gou-tu.png而不是架构图.png。5.2 Markdown编辑器里表格错位怎么办Markdown支持表格语法但问题在于如果你的表格内容特别长在部分渲染引擎中会出现错位——不是断行就是直接不显示。我的经验是表格只放短文本长文本用列表或普通段落。表格适合放二维对照信息比如参数对比、功能列表不太适合放叙述性内容。如果你确实需要一个“大表格”试试HTML的table标签虽然不纯Markdown风格但渲染兼容性更高。5.3 收件箱爆掉内容堆积成山怎么办这是纯文本方案里最容易出的问题。用了一阵子后你会发现0-inbox/文件夹里堆了上百篇笔记每周的整理节奏完全跟不上。我也有过这个阶段后来总结了一套清理方法每周挑一个固定时段我的习惯是周日上午开一个“收件箱清零”的倒计时大概设置二十五分钟。这二十五分钟只做一件事把收件箱里的文件逐篇归档。全部处理完就结束处理不完就下周继续。关键原则是不要为了归档而归档。如果某篇笔记现在没有明确的归宿就留在收件箱里等它的归属变得清晰了再处理。被强制塞进某个文件夹的笔记以后再找到它的概率反而更低。5.4 Git误操作不小心提交了敏感信息纯文本方案里Git的记录会永久保存每一次提交包含文件里可能出现的敏感内容比如密码、API密钥、个人信息。一旦提交上去即使马上删除文件这些内容还是会留在Git历史里后面的人可以翻出来看。虽然这是本地知识库不存在“后面的人”的问题但知识库同步到云端后风险就变大了。我的经验是知识库里不放敏感信息。API密钥单独用一个管理工具比如KeePass或者系统自带钥匙串来维护笔记里只写“需要用XX服务的API密钥具体见密钥管理工具”需要时再去取。看似多了一步但安全边际提升很大。如果确实不小心提交了敏感信息最稳妥的办法是用git filter-branch或者更推荐的git filter-repo工具来重写历史。但操作比较复杂我前面说的“不放敏感信息”才是治本之道。5.5 搜索结果不完整因为文件编码不对Markdown文件默认是UTF-8编码但如果从某些Windows自带编辑器拷贝出来的文本可能存成了GBK编码。这种情况下VS Code的搜索可能搜不到内容或者显示出来的中文是乱码。处理方法很简单打开文件后看VS Code右下角的状态栏如果显示GBK而不是UTF-8点一下选择“通过编码保存”再选择“UTF-8”保存即可。之后所有新文件都统一用UTF-8就不会再出这种问题了。6. 这套方案还能怎么玩自动化与发布扩展当你已经熟悉了基本操作流程可以继续往深处探索。我目前正在布局的几个进阶玩法给你做个参考与CI/CD持续集成联动我所使用的Git托管平台支持在推送代码后自动触发MkDocs构建。也就是说每次我提交笔记后个人知识库网站会自动重新生成并发布整个过程不需要我自己登录服务器操作。配合pre-commit钩子我还能在提交前自动检查文件名是否符合规范、链接是否有死链。通过R语言或Python脚本做统计因为知识库就是文件夹加Markdown文件你可以写个简单的Python脚本统计各目录下的文件数量和最近修改时间生成一张表格或图表月度查看知识库的活跃度变化趋势。这个做法能帮你直观看到自己的输入输出节奏。TiddlyWiki联动TiddlyWiki是另一种轻量级知识管理工具单个HTML文件就可以运行。有段时间我把一些高频参考内容常用命令、输入法快捷键、联系方式做成了“速查表”形式直接在浏览器里打开就能搜索定位比翻文件夹更快。这算是一个补充方案不用非得塞进Markdown体系里。但说实话方案再怎么进阶核心永远是内容本身。工具只是管道知识才是水源。这些玩意儿玩了大半年后我发现最大的实际收益不是“管理效率提升多少”而是“我丢了的东西变少了”——不管是三个月前偶然看到的一个好网站链接还是一年前自己写下的某段思考现在都能在十秒内找回来。这种感觉挺踏实的。如果你正在被信息管理问题困扰不妨从最简单的开始新建一个文件夹把记东西的工具换成纯文本编辑器坚持两周看看。不用一下子就搭完整套发布系统光是“所有内容都在一个文件夹里、用搜索就能找到”这一个体验就足够值回票价了。