很多时候技术内容适合收藏不一定因为它是最前沿的而是因为下次遇到同类问题时它能被快速找回来。浏览器收藏夹虽然能存链接但存多了之后标题模糊、没有上下文、原文失效收藏反而变成负担。真正值得长期使用的收藏方式是先把内容沉淀成 Markdown 笔记再用 Git 做版本管理最后用全文搜索和静态站点把笔记变成随时可查的本地资料库。这篇文章会从收藏场景的痛点开始逐步搭出一个最小可用的技术收藏库。你可以把它理解成一套“收藏后真的会用起来”的工程化方案统一目录、统一元数据、用脚本建笔记、用 ripgrep 搜索、用 MkDocs 生成可浏览页面。它不依赖复杂平台只要电脑上有 Git 和 Python 就能跑起来。1. 先想清楚技术收藏为什么容易变成“收藏吃灰”1.1 浏览器收藏夹的三个局限浏览器收藏夹是最容易进入的收藏工具但它并不适合沉淀技术资料。第一个局限是检索能力弱。收藏夹只能按标题和网址搜索当你只记得某个 Spring Security 过滤器的概念却不记得文章标题时只能一条条翻。第二个局限是没有上下文。技术文章通常解决一个具体问题但收藏时很少记录“当时为什么收藏”“这套配置解决的是什么场景”三个月后看到链接已经想不起当初的用途。第三个局限是内容会失效。技术文章可能被删除、改版、迁移等你想再看时链接可能已经 404。更关键的是技术收藏需要的不只是链接还包括代码片段、命令、参数、验证方式和踩坑记录。这些内容散落在不同文章里如果没有统一整理很难在写代码时复用。1.2 技术笔记和普通剪藏的标准不一样普通网页剪藏看重“原文完整”技术笔记更看重“可复现”。一篇技术文章收藏后真正有用的部分是它解决什么问题、结论是什么、关键命令或代码是什么、验证方式是什么。这四类内容如果没被单独提炼收藏再完整也没用。另外技术笔记需要持续更新。比如某个框架的新版本修改了配置方式旧笔记里的方案可能已经过时。如果收藏方式不支持修改、回溯和重新标记状态过时内容就会一直混在库里。1.3 一个可用的收藏库应该满足哪些条件结合日常开发场景一个可长期使用的技术收藏库至少应该满足四个条件内容以 Markdown 保存纯文本、可读、可迁移。每篇笔记都带元数据包括标题、标签、来源、创建时间、更新时间和状态。支持本地全文搜索能按关键词、标签、领域快速定位。有版本管理能力修改、删除、同步都留下历史记录。这套方案里Markdown 负责内容组织Git 负责历史回溯ripgrep 负责检索MkDocs 负责把笔记渲染成可浏览的页面。它们各自解决一个环节组合起来就是一个不依赖任何在线平台的知识库。2. 先统一目录、命名和元数据否则后面检索会越来越乱2.1 目录结构按领域而不是按时间分很多人的收藏分类喜欢按“2025年资料”“4月文章”之类的时间维度但技术检索通常是从问题出发而不是从时间出发。更合理的做法是按领域划分每个领域是一个顶层目录。一个适合大多数后端开发、前端开发和运维场景的目录结构tech-notes/ ├── README.md ├── mkdocs.yml ├── docs/ │ ├── index.md │ ├── frontend/ │ ├── backend/ │ ├── devops/ │ ├── database/ │ ├── tools/ │ ├── career/ │ └── _attachments/ ├── _templates/ │ └── note-template.md └── scripts/ └── new_note.py目录命名的原则是让新笔记能一眼找到“该放哪”。frontend放前端框架、页面性能、组件设计backend放服务端框架、接口设计、业务逻辑devops放 CI/CD、容器、监控、部署database放 SQL、索引、数据库中间件tools放 Git、编辑器、命令行工具、脚本career放项目复盘、技术管理、学习方法。_attachments专门放图片或无法内嵌的二进制文件_templates放新建笔记的模板scripts放自动创建笔记的脚本。这样目录本身已经承担了一部分分类检索能力。2.2 文件名规则机器可读人也容易识别文件名是笔记的第一层标识。建议使用小写字母、数字和连字符并用短横线分隔语义单元。例如spring-security-filter-chain.mdnginx-location-match-rule.mdmysql-index-left-prefix.md不建议把完整文章标题当作文件名。很多文章标题太长还包含问号、冒号、空格这些字符在部分系统或链接工具里容易出问题。如果希望保留一定可读性可以在文件名中保留少量中文但尽量控制在 60 个字符以内。给文件名加日期前缀也是一种可选方案例如2025-04-01-spring-security-filter-chain.md。日期前缀适合“笔记内容会持续积累”的场景因为同一天新建同名笔记的概率较低重复文件名不至于互相覆盖。2.3 用 YAML front matter 给笔记带上上下文Markdown 本身只保存正文不保存“来源地址”“创建时间”“标签”这类信息。YAML front matter 是 Markdown 文件开头的一段元数据很多 Markdown 工具和静态站点生成器都支持它。每篇笔记都应该在文件最顶部写清楚上下文。一个完整的 front matter 示例--- title: Spring Security 过滤器链排查记录 tags: [Java, Spring Security, 排错] created: 2025-04-01 updated: 2025-04-06 source: https://example.com/spring-security-filter-chain status: collected importance: 4 ---字段含义和作用字段作用建议title笔记标题尽量写“解决什么问题”而不是原文标题tags标签列表控制在 3 到 5 个便于归类created创建日期使用 YYYY-MM-DD 格式updated最后更新日期每次修改后手动或脚本更新source原始链接保留出处方便追溯原文和补全细节status笔记状态collected、processed、expired 三选一importance重要程度1 到 5用于后续筛选status字段是技术收藏库和普通剪藏最大的区别。新建笔记默认是collected表示刚从外部收集回来还没有提炼完成整理过、验证过后改成processed确认方案已经过时或不再适用再改成expired。这样每次检索都能过滤掉过时内容。注意front matter 必须写在文件最顶部以---开头以---结束否则 MkDocs 等内容解析工具可能把它当普通正文处理。3. 初始化本地 Git 仓库并准备模板3.1 安装 Git 和 ripgrep本地收藏库最基本的依赖只有两个Git 和 ripgrep。Git 负责版本管理ripgrep 负责快速全文搜索。Markdown 不需要安装额外依赖任何编辑器都能写。不同系统的安装方式如下平台Git 安装ripgrep 安装macOSbrew install gitbrew install ripgrepUbuntu / Debiansudo apt update sudo apt install gitsudo apt update sudo apt install ripgrepWindows安装 Git for Windowswinget install BurntSushi.ripgrep.MSVC安装完成后先确认版本。如果命令能输出版本号说明环境正常git --version rg --version在 Windows 上如果执行python3不生效可以改用py命令。后续脚本中的python3可根据实际环境替换。3.2 初始化仓库和目录打开命令行进入想存放知识库的目录然后创建项目文件夹并初始化 Gitmkdir tech-notes cd tech-notes git init mkdir -p docs/{frontend,backend,devops,database,tools,career,_attachments} _templates scripts上面的mkdir -p命令适合在 Bash、Git Bash 或 WSL 中执行。如果使用 Windows 原生命令行需要逐个创建目录或者直接使用资源管理器新建。初始化 Git 的目的不是为了让本地文件多个.git文件夹而是让每一次修改都能被回溯。比如某天整理目录时误删了一条笔记可以通过git log和git checkout找回。3.3 创建笔记模板和 .gitignore在_templates/note-template.md中创建一个空白模板每次新建笔记都从它复制--- title: 笔记标题 tags: [] created: 2025-01-01 updated: 2025-01-01 source: status: collected importance: 3 --- # 笔记标题 ## 为什么收藏 ## 核心内容 ## 关键命令 / 配置 / 代码 ## 验证方式 ## 后续待做模板的价值是让每篇笔记保持统一结构避免“有些笔记写标签有些笔记不写标签”的情况。建议至少保留为什么收藏、核心内容、验证方式三个小节。再创建.gitignore把不需要提交的文件排除掉site/ __pycache__/ .DS_Store *.tmpsite/是 MkDocs 生成静态站点时的输出目录属于构建产物不需要纳入版本管理。__pycache__/是 Python 脚本运行时的缓存目录。创建完模板和.gitignore后做一次初始提交git add . git commit -m init tech notes repository提交记录会成为整个收藏库的第一个历史节点。4. 写一个快速收藏脚本避免手工维护 front matter4.1 脚本要解决什么手工创建 Markdown 笔记并不难难的是每次都记得写完整的 front matter、选择正确目录、生成规范文件名。只要有一次偷懒笔记就会变成没有元数据的纯文本后续检索能力立刻下降。一个简单的 Python 脚本可以解决这个问题。它接收类别、标题、来源和标签自动计算文件名生成 front matter并输出到对应目录。这样“收藏”的动作就从“复制粘贴网址”变成“补充一句话说明”上下文自然被保留下来。4.2 Python 脚本实现在scripts/new_note.py中写入以下脚本#!/usr/bin/env python3 Create a new markdown note from a few command line arguments. import argparse import re import sys from datetime import date from pathlib import Path ALLOWED_CATEGORIES {frontend, backend, devops, database, tools, career} parser argparse.ArgumentParser(descriptionCreate a new tech note) parser.add_argument(category, choicessorted(ALLOWED_CATEGORIES)) parser.add_argument(title, helpnote title) parser.add_argument(--source, default, helporiginal article URL) parser.add_argument(--tags, default, helpcomma separated tags) args parser.parse_args() today date.today().isoformat() slug re.sub(r[^a-z0-9\u4e00-\u9fff], -, args.title.lower()) slug slug.strip(-)[:60] filename f{today}-{slug}.md out_dir Path(docs) / args.category out_dir.mkdir(parentsTrue, exist_okTrue) out out_dir / filename if out.exists(): print(ffile already exists: {out}, filesys.stderr) sys.exit(1) tags [tag.strip() for tag in args.tags.split(,) if tag.strip()] tags_yaml [ , .join( tag for tag in tags) ] template f--- title: {args.title} tags: {tags_yaml} created: {today} updated: {today} source: {args.source} status: collected importance: 3 --- # {args.title} ## 为什么收藏 ## 核心内容 ## 关键命令 / 配置 / 代码 ## 验证方式 ## 后续待做 out.write_text(template, encodingutf-8) print(fcreated: {out})这段脚本有几个关键点。第一ALLOWED_CATEGORIES限制了类别避免随手输入一个不存在目录导致笔记被放到错误位置。第二正则表达式把标题里的空格和非字母数字字符转成连字符生成一个相对工整的文件名。第三脚本检查输出文件是否已存在若存在就退出避免重复创建并覆盖旧笔记。第四写入文件时显式指定encodingutf-8保证在 Windows 或者不同语言环境下不乱码。4.3 使用示例和参数说明在项目根目录运行脚本python3 scripts/new_note.py backend Spring Security 过滤器链排查记录 \ --source https://example.com/spring-security-filter-chain \ --tags Java,Spring Security,排错运行后脚本会创建一个类似docs/backend/2025-04-01-spring-security-过滤器链排查记录.md的文件并打开文件可以看到自动生成的 front matter 和空模板。参数说明参数含义是否必填示例category笔记领域必填backend、devops、toolstitle笔记标题必填Nginx location 匹配规则--source原始链接选填https://example.com/nginx-location--tags标签列表选填Nginx,运维,配置运行脚本后可以先查看生成的文件内容再检查 Git 状态cat docs/backend/*.md git status如果文件内容正确就完成了第一次“脚本式收藏”。注意收藏不是把原文整篇复制进来。应该只提炼自己的理解、关键命令和验证方式保留原链接。整篇复制不仅难以维护也可能带来版权问题。5. 用全文搜索和静态站点把笔记真正用起来5.1 用 ripgrep 找回以前的解决问题记录笔记积累到几百篇后靠目录浏览效率太低全文搜索才是主要的入口。常见搜索命令rg -n Spring Security docs rg -l 数据库连接池 docs rg -l status: collected docsrg -n会显示匹配行号和内容适合精确定位知识点。rg -l只显示包含匹配内容的文件适合先筛文件再打开。第三种命令可以找出所有还处于collected状态、尚未整理的笔记。如果想跳过附件目录可以使用-g参数rg -n 内存溢出 docs -g !docs/_attachments/**ripgrep 默认会遵守.gitignore如果某些目录已经在.gitignore中它不会搜索那些目录。实际开发中可以形成这样一个习惯排障时先搜索本地收藏库再搜索外部网络。因为本地笔记记录的是自己以前踩过的坑针对性往往比通用文章更强。5.2 用 MkDocs 生成可浏览的本地文档站纯 Markdown 文件可以看但没有目录、没有搜索框、没有阅读样式。如果希望把知识库变成一个可浏览的静态站点可以使用 MkDocs。安装 MkDocs Material 主题python3 -m pip install mkdocs-material在项目根目录创建mkdocs.ymlsite_name: Tech Notes site_dir: site docs_dir: docs theme: name: material plugins: - searchdocs_dir指向 Markdown 文件所在目录site_dir指向构建输出目录。这里需要注意docs目录下需要有一个index.md否则首页会显示目录列表而不是内容。可以先在docs/index.md中写一个简短说明# Tech Notes 个人技术收藏库按领域整理使用 Git 管理历史使用全文搜索定位内容。然后在项目根目录执行mkdocs serve浏览器访问http://127.0.0.1:8000就能看到本地文档站。确认没有问题后可以执行mkdocs build生成静态页面输出到site目录。MkDocs 的价值主要是让笔记在浏览器里有更好的阅读体验。如果只追求本地文本检索完全可以不用这一步。5.3 通过 README 维护高频入口全文搜索适合“找内容”README 适合“放高频入口”。可以在README.md里维护一个经常需要翻开的页面清单例如公司内部规范、常用部署流程、数据库备份脚本等。README 不需要长只要放几个最常见的入口即可# Tech Notes ## 常用入口 - [Nginx 常用配置](docs/devops/nginx-common-config.md) - [MySQL 索引设计笔记](docs/database/mysql-index-design.md) - [Java 线上问题排查流程](docs/backend/java-online-troubleshooting.md) ## 目录说明 - backend后端框架、服务端设计、线上问题 - devops容器、部署、CI/CD、监控 - databaseSQL、索引、中间件 - tools开发工具、命令行、脚本README 的常用入口可以定期根据搜索频率调整确保最关键的信息永远能通过一两次点击到达。6. 收藏库使用中的常见问题排查6.1 找不到笔记现象是刚创建的笔记下次找不到了。先确认脚本输出的路径。如果运行脚本时使用了错误的工作目录文件可能被放到了其他位置。检查方式pwd ls docs ls docs/backend再检查是否提交到了 Git。如果只是创建了文件但没有git add在另一个设备上同步时自然找不到git status git log --oneline --stat处理方式是确认脚本运行目录在项目根目录并把整个收藏库的目录结构固定下来不要在不同设备上随意改名。问题现象常见原因检查方式处理建议新笔记找不到运行目录不对或目录结构不一致pwd、ls固定项目根目录脚本在根目录运行别的设备没有这篇文章本地文件未提交或未推送git status、git log养成创建后立即提交的习惯文件名和预期不一致标题造出的文件名过长或特殊字符被替换ls docs/backend清晰标题脚本自动生成短文件名6.2 搜索不到内容现象是用rg搜一个明显存在的词语却没有结果。优先检查文件编码。如果文件使用 GBK 或 UTF-8 with BOM 保存ripgrep 按 UTF-8 搜索时可能匹配不到中文。检查方式file docs/backend/*.md输出里如果没有UTF-8就需要重新保存文件。另外如果搜索词包含空格或特殊符号记得给关键词加引号。Windows 的 PowerShell 和 Git Bash 对引号的处理不完全一样搜索中文内容时优先使用简单不加引号的单词测试。还有一个常见原因是搜索路径不对。如果当前目录在项目根目录以下直接rg 关键词只能搜索当前目录和子目录搜不到docs外或上级目录的内容。建议固定使用rg 关键词 docs6.3 Git 冲突和文件覆盖在多个设备之间维护同一份笔记库时如果两个设备都修改了同一个文件Git 会提示冲突。现象是git pull后出现CONFLICT或者文件里出现 HEAD的分隔符。处理方式不要直接强制覆盖先看冲突内容git status git diff如果是同一篇笔记在两个设备上补充了不同内容需要手动合并保留两个版本的信息然后重新提交。如果只是单方面修改可以先git pull --rebase让本地提交先暂存到远端提交之上再根据提示处理冲突。养成“编辑前先 pull提交前先 status”的习惯可以大幅减少冲突。6.4 Markdown 渲染异常现象是在 MkDocs 页面里笔记标题没有正常显示或者 front matter 被当作正文输出。通常原因是 front matter 没有放在文件最顶部或者 YAML 中引号没有闭合。检查文件开头head -n 5 docs/backend/xxx.md如果第一行不是---说明文件保存时前面多了空行或注释。修正方式是把---放到第一行。还有一个常见问题是 YAML 中source地址包含冒号和#时没有加引号。脚本生成时已经给source加了引号但如果手工修改 front matter要注意保持引号闭合。7. 让收藏真正变成可复用资产三份清单7.1 新建一篇笔记时的检查清单每新建一篇笔记都检查以下内容标题是否说明“解决什么问题”而不是简单照搬原文标题。是否补了“为什么收藏”哪怕只有一句话。是否提炼了“核心内容”的至少三个要点。是否包含关键命令、配置或代码。是否写了“验证方式”即如何确认这个方案有效。是否保留原始链接。标签数量是否控制在 3 到 5 个。如果这几项都满足这篇笔记才算真正入库。7.2 每周整理清单收藏库不是建完就结束需要保持更新。每周花 15 分钟整理一次打开浏览器收藏夹把临时收藏的文章按脚本建笔记。搜索status: collected的笔记逐条决定转成processed还是删除。删除失效链接保留自己写的摘要和关键代码。检查前天写的笔记是否有补充内容有则更新updated字段。把高频使用入口更新到 README。整理的目标不是追求数量而是确保库里的内容都经过了验证需要时能找到。7.3 入库前淘汰标准不是所有文章都值得进入收藏库。建议先过滤以下内容只有观点、没有技术细节或代码的文章。已经确定过时且不可能再使用的内容。与当前技术栈无关且未来半年不会接触的领域。整篇复制他人的原文而没有自己的补充。收藏的价值在于“查找次数”和“复用次数”不在于数量。保留少量高质量笔记比囤积大量低质量链接更有用。8. 扩展方向从个人知识库到团队研发资产8.1 把笔记接入日常开发流程本地收藏库最自然的用法是把它当成开发的“第二入口”。遇到报错时先rg 报错关键字 docs而不是直接打开搜索引擎。因为以前记下来的笔记通常记录了当时的环境、命令和验证方式比通用搜索更贴近自己的项目。也可以在脚本里增加更多参数比如关联项目名、问题优先级、复现步骤把单纯的技术收藏升级成问题案例库。8.2 链接检查与自动构建当笔记量变大后外链失效会越来越严重。可以定期扫描 Markdown 文件中的外部链接。如果环境中有 Node.js可以用 linkinator 这类链接检查工具npx linkinator docs --recurse输出里会标记哪些链接返回 404再决定是更新链接还是移除这篇笔记。如果收藏库放在支持 CI 的 Git 平台上还可以配置流水线在每次提交后自动执行mkdocs build并把site目录发布到内部文档服务。这样团队成员不需要安装 MkDocs也能浏览整理好的技术文档。8.3 适合进一步学习的实践如果想把这套方案做得更深入可以继续研究Git 分支策略把 “已整理” 和 “待整理” 分开用分支表示不同状态。标签体系设计统一标签命名避免出现同类概念多个叫法。自动化脚本让脚本支持从剪藏内容中提取标题和 URL。全文检索增强引入 SQLite FTS 或更专业的本地搜索引擎。技术收藏不是目的能随时找到并使用才是目的。Markdown 和 Git 的组合不需要复杂平台也不需要在线服务它只是把笔记当成代码一样管理留下历史、保留上下文、可以检索、可以迭代。建议先从最小方案开始坚持录入几篇笔记等积累了问题后再逐步加入自动化。真正值得收藏的永远是那些能被反复翻出来解决问题的内容。
Markdown+Git+ripgrep：打造可检索可回溯的技术收藏库
很多时候技术内容适合收藏不一定因为它是最前沿的而是因为下次遇到同类问题时它能被快速找回来。浏览器收藏夹虽然能存链接但存多了之后标题模糊、没有上下文、原文失效收藏反而变成负担。真正值得长期使用的收藏方式是先把内容沉淀成 Markdown 笔记再用 Git 做版本管理最后用全文搜索和静态站点把笔记变成随时可查的本地资料库。这篇文章会从收藏场景的痛点开始逐步搭出一个最小可用的技术收藏库。你可以把它理解成一套“收藏后真的会用起来”的工程化方案统一目录、统一元数据、用脚本建笔记、用 ripgrep 搜索、用 MkDocs 生成可浏览页面。它不依赖复杂平台只要电脑上有 Git 和 Python 就能跑起来。1. 先想清楚技术收藏为什么容易变成“收藏吃灰”1.1 浏览器收藏夹的三个局限浏览器收藏夹是最容易进入的收藏工具但它并不适合沉淀技术资料。第一个局限是检索能力弱。收藏夹只能按标题和网址搜索当你只记得某个 Spring Security 过滤器的概念却不记得文章标题时只能一条条翻。第二个局限是没有上下文。技术文章通常解决一个具体问题但收藏时很少记录“当时为什么收藏”“这套配置解决的是什么场景”三个月后看到链接已经想不起当初的用途。第三个局限是内容会失效。技术文章可能被删除、改版、迁移等你想再看时链接可能已经 404。更关键的是技术收藏需要的不只是链接还包括代码片段、命令、参数、验证方式和踩坑记录。这些内容散落在不同文章里如果没有统一整理很难在写代码时复用。1.2 技术笔记和普通剪藏的标准不一样普通网页剪藏看重“原文完整”技术笔记更看重“可复现”。一篇技术文章收藏后真正有用的部分是它解决什么问题、结论是什么、关键命令或代码是什么、验证方式是什么。这四类内容如果没被单独提炼收藏再完整也没用。另外技术笔记需要持续更新。比如某个框架的新版本修改了配置方式旧笔记里的方案可能已经过时。如果收藏方式不支持修改、回溯和重新标记状态过时内容就会一直混在库里。1.3 一个可用的收藏库应该满足哪些条件结合日常开发场景一个可长期使用的技术收藏库至少应该满足四个条件内容以 Markdown 保存纯文本、可读、可迁移。每篇笔记都带元数据包括标题、标签、来源、创建时间、更新时间和状态。支持本地全文搜索能按关键词、标签、领域快速定位。有版本管理能力修改、删除、同步都留下历史记录。这套方案里Markdown 负责内容组织Git 负责历史回溯ripgrep 负责检索MkDocs 负责把笔记渲染成可浏览的页面。它们各自解决一个环节组合起来就是一个不依赖任何在线平台的知识库。2. 先统一目录、命名和元数据否则后面检索会越来越乱2.1 目录结构按领域而不是按时间分很多人的收藏分类喜欢按“2025年资料”“4月文章”之类的时间维度但技术检索通常是从问题出发而不是从时间出发。更合理的做法是按领域划分每个领域是一个顶层目录。一个适合大多数后端开发、前端开发和运维场景的目录结构tech-notes/ ├── README.md ├── mkdocs.yml ├── docs/ │ ├── index.md │ ├── frontend/ │ ├── backend/ │ ├── devops/ │ ├── database/ │ ├── tools/ │ ├── career/ │ └── _attachments/ ├── _templates/ │ └── note-template.md └── scripts/ └── new_note.py目录命名的原则是让新笔记能一眼找到“该放哪”。frontend放前端框架、页面性能、组件设计backend放服务端框架、接口设计、业务逻辑devops放 CI/CD、容器、监控、部署database放 SQL、索引、数据库中间件tools放 Git、编辑器、命令行工具、脚本career放项目复盘、技术管理、学习方法。_attachments专门放图片或无法内嵌的二进制文件_templates放新建笔记的模板scripts放自动创建笔记的脚本。这样目录本身已经承担了一部分分类检索能力。2.2 文件名规则机器可读人也容易识别文件名是笔记的第一层标识。建议使用小写字母、数字和连字符并用短横线分隔语义单元。例如spring-security-filter-chain.mdnginx-location-match-rule.mdmysql-index-left-prefix.md不建议把完整文章标题当作文件名。很多文章标题太长还包含问号、冒号、空格这些字符在部分系统或链接工具里容易出问题。如果希望保留一定可读性可以在文件名中保留少量中文但尽量控制在 60 个字符以内。给文件名加日期前缀也是一种可选方案例如2025-04-01-spring-security-filter-chain.md。日期前缀适合“笔记内容会持续积累”的场景因为同一天新建同名笔记的概率较低重复文件名不至于互相覆盖。2.3 用 YAML front matter 给笔记带上上下文Markdown 本身只保存正文不保存“来源地址”“创建时间”“标签”这类信息。YAML front matter 是 Markdown 文件开头的一段元数据很多 Markdown 工具和静态站点生成器都支持它。每篇笔记都应该在文件最顶部写清楚上下文。一个完整的 front matter 示例--- title: Spring Security 过滤器链排查记录 tags: [Java, Spring Security, 排错] created: 2025-04-01 updated: 2025-04-06 source: https://example.com/spring-security-filter-chain status: collected importance: 4 ---字段含义和作用字段作用建议title笔记标题尽量写“解决什么问题”而不是原文标题tags标签列表控制在 3 到 5 个便于归类created创建日期使用 YYYY-MM-DD 格式updated最后更新日期每次修改后手动或脚本更新source原始链接保留出处方便追溯原文和补全细节status笔记状态collected、processed、expired 三选一importance重要程度1 到 5用于后续筛选status字段是技术收藏库和普通剪藏最大的区别。新建笔记默认是collected表示刚从外部收集回来还没有提炼完成整理过、验证过后改成processed确认方案已经过时或不再适用再改成expired。这样每次检索都能过滤掉过时内容。注意front matter 必须写在文件最顶部以---开头以---结束否则 MkDocs 等内容解析工具可能把它当普通正文处理。3. 初始化本地 Git 仓库并准备模板3.1 安装 Git 和 ripgrep本地收藏库最基本的依赖只有两个Git 和 ripgrep。Git 负责版本管理ripgrep 负责快速全文搜索。Markdown 不需要安装额外依赖任何编辑器都能写。不同系统的安装方式如下平台Git 安装ripgrep 安装macOSbrew install gitbrew install ripgrepUbuntu / Debiansudo apt update sudo apt install gitsudo apt update sudo apt install ripgrepWindows安装 Git for Windowswinget install BurntSushi.ripgrep.MSVC安装完成后先确认版本。如果命令能输出版本号说明环境正常git --version rg --version在 Windows 上如果执行python3不生效可以改用py命令。后续脚本中的python3可根据实际环境替换。3.2 初始化仓库和目录打开命令行进入想存放知识库的目录然后创建项目文件夹并初始化 Gitmkdir tech-notes cd tech-notes git init mkdir -p docs/{frontend,backend,devops,database,tools,career,_attachments} _templates scripts上面的mkdir -p命令适合在 Bash、Git Bash 或 WSL 中执行。如果使用 Windows 原生命令行需要逐个创建目录或者直接使用资源管理器新建。初始化 Git 的目的不是为了让本地文件多个.git文件夹而是让每一次修改都能被回溯。比如某天整理目录时误删了一条笔记可以通过git log和git checkout找回。3.3 创建笔记模板和 .gitignore在_templates/note-template.md中创建一个空白模板每次新建笔记都从它复制--- title: 笔记标题 tags: [] created: 2025-01-01 updated: 2025-01-01 source: status: collected importance: 3 --- # 笔记标题 ## 为什么收藏 ## 核心内容 ## 关键命令 / 配置 / 代码 ## 验证方式 ## 后续待做模板的价值是让每篇笔记保持统一结构避免“有些笔记写标签有些笔记不写标签”的情况。建议至少保留为什么收藏、核心内容、验证方式三个小节。再创建.gitignore把不需要提交的文件排除掉site/ __pycache__/ .DS_Store *.tmpsite/是 MkDocs 生成静态站点时的输出目录属于构建产物不需要纳入版本管理。__pycache__/是 Python 脚本运行时的缓存目录。创建完模板和.gitignore后做一次初始提交git add . git commit -m init tech notes repository提交记录会成为整个收藏库的第一个历史节点。4. 写一个快速收藏脚本避免手工维护 front matter4.1 脚本要解决什么手工创建 Markdown 笔记并不难难的是每次都记得写完整的 front matter、选择正确目录、生成规范文件名。只要有一次偷懒笔记就会变成没有元数据的纯文本后续检索能力立刻下降。一个简单的 Python 脚本可以解决这个问题。它接收类别、标题、来源和标签自动计算文件名生成 front matter并输出到对应目录。这样“收藏”的动作就从“复制粘贴网址”变成“补充一句话说明”上下文自然被保留下来。4.2 Python 脚本实现在scripts/new_note.py中写入以下脚本#!/usr/bin/env python3 Create a new markdown note from a few command line arguments. import argparse import re import sys from datetime import date from pathlib import Path ALLOWED_CATEGORIES {frontend, backend, devops, database, tools, career} parser argparse.ArgumentParser(descriptionCreate a new tech note) parser.add_argument(category, choicessorted(ALLOWED_CATEGORIES)) parser.add_argument(title, helpnote title) parser.add_argument(--source, default, helporiginal article URL) parser.add_argument(--tags, default, helpcomma separated tags) args parser.parse_args() today date.today().isoformat() slug re.sub(r[^a-z0-9\u4e00-\u9fff], -, args.title.lower()) slug slug.strip(-)[:60] filename f{today}-{slug}.md out_dir Path(docs) / args.category out_dir.mkdir(parentsTrue, exist_okTrue) out out_dir / filename if out.exists(): print(ffile already exists: {out}, filesys.stderr) sys.exit(1) tags [tag.strip() for tag in args.tags.split(,) if tag.strip()] tags_yaml [ , .join( tag for tag in tags) ] template f--- title: {args.title} tags: {tags_yaml} created: {today} updated: {today} source: {args.source} status: collected importance: 3 --- # {args.title} ## 为什么收藏 ## 核心内容 ## 关键命令 / 配置 / 代码 ## 验证方式 ## 后续待做 out.write_text(template, encodingutf-8) print(fcreated: {out})这段脚本有几个关键点。第一ALLOWED_CATEGORIES限制了类别避免随手输入一个不存在目录导致笔记被放到错误位置。第二正则表达式把标题里的空格和非字母数字字符转成连字符生成一个相对工整的文件名。第三脚本检查输出文件是否已存在若存在就退出避免重复创建并覆盖旧笔记。第四写入文件时显式指定encodingutf-8保证在 Windows 或者不同语言环境下不乱码。4.3 使用示例和参数说明在项目根目录运行脚本python3 scripts/new_note.py backend Spring Security 过滤器链排查记录 \ --source https://example.com/spring-security-filter-chain \ --tags Java,Spring Security,排错运行后脚本会创建一个类似docs/backend/2025-04-01-spring-security-过滤器链排查记录.md的文件并打开文件可以看到自动生成的 front matter 和空模板。参数说明参数含义是否必填示例category笔记领域必填backend、devops、toolstitle笔记标题必填Nginx location 匹配规则--source原始链接选填https://example.com/nginx-location--tags标签列表选填Nginx,运维,配置运行脚本后可以先查看生成的文件内容再检查 Git 状态cat docs/backend/*.md git status如果文件内容正确就完成了第一次“脚本式收藏”。注意收藏不是把原文整篇复制进来。应该只提炼自己的理解、关键命令和验证方式保留原链接。整篇复制不仅难以维护也可能带来版权问题。5. 用全文搜索和静态站点把笔记真正用起来5.1 用 ripgrep 找回以前的解决问题记录笔记积累到几百篇后靠目录浏览效率太低全文搜索才是主要的入口。常见搜索命令rg -n Spring Security docs rg -l 数据库连接池 docs rg -l status: collected docsrg -n会显示匹配行号和内容适合精确定位知识点。rg -l只显示包含匹配内容的文件适合先筛文件再打开。第三种命令可以找出所有还处于collected状态、尚未整理的笔记。如果想跳过附件目录可以使用-g参数rg -n 内存溢出 docs -g !docs/_attachments/**ripgrep 默认会遵守.gitignore如果某些目录已经在.gitignore中它不会搜索那些目录。实际开发中可以形成这样一个习惯排障时先搜索本地收藏库再搜索外部网络。因为本地笔记记录的是自己以前踩过的坑针对性往往比通用文章更强。5.2 用 MkDocs 生成可浏览的本地文档站纯 Markdown 文件可以看但没有目录、没有搜索框、没有阅读样式。如果希望把知识库变成一个可浏览的静态站点可以使用 MkDocs。安装 MkDocs Material 主题python3 -m pip install mkdocs-material在项目根目录创建mkdocs.ymlsite_name: Tech Notes site_dir: site docs_dir: docs theme: name: material plugins: - searchdocs_dir指向 Markdown 文件所在目录site_dir指向构建输出目录。这里需要注意docs目录下需要有一个index.md否则首页会显示目录列表而不是内容。可以先在docs/index.md中写一个简短说明# Tech Notes 个人技术收藏库按领域整理使用 Git 管理历史使用全文搜索定位内容。然后在项目根目录执行mkdocs serve浏览器访问http://127.0.0.1:8000就能看到本地文档站。确认没有问题后可以执行mkdocs build生成静态页面输出到site目录。MkDocs 的价值主要是让笔记在浏览器里有更好的阅读体验。如果只追求本地文本检索完全可以不用这一步。5.3 通过 README 维护高频入口全文搜索适合“找内容”README 适合“放高频入口”。可以在README.md里维护一个经常需要翻开的页面清单例如公司内部规范、常用部署流程、数据库备份脚本等。README 不需要长只要放几个最常见的入口即可# Tech Notes ## 常用入口 - [Nginx 常用配置](docs/devops/nginx-common-config.md) - [MySQL 索引设计笔记](docs/database/mysql-index-design.md) - [Java 线上问题排查流程](docs/backend/java-online-troubleshooting.md) ## 目录说明 - backend后端框架、服务端设计、线上问题 - devops容器、部署、CI/CD、监控 - databaseSQL、索引、中间件 - tools开发工具、命令行、脚本README 的常用入口可以定期根据搜索频率调整确保最关键的信息永远能通过一两次点击到达。6. 收藏库使用中的常见问题排查6.1 找不到笔记现象是刚创建的笔记下次找不到了。先确认脚本输出的路径。如果运行脚本时使用了错误的工作目录文件可能被放到了其他位置。检查方式pwd ls docs ls docs/backend再检查是否提交到了 Git。如果只是创建了文件但没有git add在另一个设备上同步时自然找不到git status git log --oneline --stat处理方式是确认脚本运行目录在项目根目录并把整个收藏库的目录结构固定下来不要在不同设备上随意改名。问题现象常见原因检查方式处理建议新笔记找不到运行目录不对或目录结构不一致pwd、ls固定项目根目录脚本在根目录运行别的设备没有这篇文章本地文件未提交或未推送git status、git log养成创建后立即提交的习惯文件名和预期不一致标题造出的文件名过长或特殊字符被替换ls docs/backend清晰标题脚本自动生成短文件名6.2 搜索不到内容现象是用rg搜一个明显存在的词语却没有结果。优先检查文件编码。如果文件使用 GBK 或 UTF-8 with BOM 保存ripgrep 按 UTF-8 搜索时可能匹配不到中文。检查方式file docs/backend/*.md输出里如果没有UTF-8就需要重新保存文件。另外如果搜索词包含空格或特殊符号记得给关键词加引号。Windows 的 PowerShell 和 Git Bash 对引号的处理不完全一样搜索中文内容时优先使用简单不加引号的单词测试。还有一个常见原因是搜索路径不对。如果当前目录在项目根目录以下直接rg 关键词只能搜索当前目录和子目录搜不到docs外或上级目录的内容。建议固定使用rg 关键词 docs6.3 Git 冲突和文件覆盖在多个设备之间维护同一份笔记库时如果两个设备都修改了同一个文件Git 会提示冲突。现象是git pull后出现CONFLICT或者文件里出现 HEAD的分隔符。处理方式不要直接强制覆盖先看冲突内容git status git diff如果是同一篇笔记在两个设备上补充了不同内容需要手动合并保留两个版本的信息然后重新提交。如果只是单方面修改可以先git pull --rebase让本地提交先暂存到远端提交之上再根据提示处理冲突。养成“编辑前先 pull提交前先 status”的习惯可以大幅减少冲突。6.4 Markdown 渲染异常现象是在 MkDocs 页面里笔记标题没有正常显示或者 front matter 被当作正文输出。通常原因是 front matter 没有放在文件最顶部或者 YAML 中引号没有闭合。检查文件开头head -n 5 docs/backend/xxx.md如果第一行不是---说明文件保存时前面多了空行或注释。修正方式是把---放到第一行。还有一个常见问题是 YAML 中source地址包含冒号和#时没有加引号。脚本生成时已经给source加了引号但如果手工修改 front matter要注意保持引号闭合。7. 让收藏真正变成可复用资产三份清单7.1 新建一篇笔记时的检查清单每新建一篇笔记都检查以下内容标题是否说明“解决什么问题”而不是简单照搬原文标题。是否补了“为什么收藏”哪怕只有一句话。是否提炼了“核心内容”的至少三个要点。是否包含关键命令、配置或代码。是否写了“验证方式”即如何确认这个方案有效。是否保留原始链接。标签数量是否控制在 3 到 5 个。如果这几项都满足这篇笔记才算真正入库。7.2 每周整理清单收藏库不是建完就结束需要保持更新。每周花 15 分钟整理一次打开浏览器收藏夹把临时收藏的文章按脚本建笔记。搜索status: collected的笔记逐条决定转成processed还是删除。删除失效链接保留自己写的摘要和关键代码。检查前天写的笔记是否有补充内容有则更新updated字段。把高频使用入口更新到 README。整理的目标不是追求数量而是确保库里的内容都经过了验证需要时能找到。7.3 入库前淘汰标准不是所有文章都值得进入收藏库。建议先过滤以下内容只有观点、没有技术细节或代码的文章。已经确定过时且不可能再使用的内容。与当前技术栈无关且未来半年不会接触的领域。整篇复制他人的原文而没有自己的补充。收藏的价值在于“查找次数”和“复用次数”不在于数量。保留少量高质量笔记比囤积大量低质量链接更有用。8. 扩展方向从个人知识库到团队研发资产8.1 把笔记接入日常开发流程本地收藏库最自然的用法是把它当成开发的“第二入口”。遇到报错时先rg 报错关键字 docs而不是直接打开搜索引擎。因为以前记下来的笔记通常记录了当时的环境、命令和验证方式比通用搜索更贴近自己的项目。也可以在脚本里增加更多参数比如关联项目名、问题优先级、复现步骤把单纯的技术收藏升级成问题案例库。8.2 链接检查与自动构建当笔记量变大后外链失效会越来越严重。可以定期扫描 Markdown 文件中的外部链接。如果环境中有 Node.js可以用 linkinator 这类链接检查工具npx linkinator docs --recurse输出里会标记哪些链接返回 404再决定是更新链接还是移除这篇笔记。如果收藏库放在支持 CI 的 Git 平台上还可以配置流水线在每次提交后自动执行mkdocs build并把site目录发布到内部文档服务。这样团队成员不需要安装 MkDocs也能浏览整理好的技术文档。8.3 适合进一步学习的实践如果想把这套方案做得更深入可以继续研究Git 分支策略把 “已整理” 和 “待整理” 分开用分支表示不同状态。标签体系设计统一标签命名避免出现同类概念多个叫法。自动化脚本让脚本支持从剪藏内容中提取标题和 URL。全文检索增强引入 SQLite FTS 或更专业的本地搜索引擎。技术收藏不是目的能随时找到并使用才是目的。Markdown 和 Git 的组合不需要复杂平台也不需要在线服务它只是把笔记当成代码一样管理留下历史、保留上下文、可以检索、可以迭代。建议先从最小方案开始坚持录入几篇笔记等积累了问题后再逐步加入自动化。真正值得收藏的永远是那些能被反复翻出来解决问题的内容。
