Foam for VS Code 深度指南用 Markdown Wikilinks 构建本地优先的个人知识库【免费下载链接】foamA personal knowledge management and sharing system for VSCode项目地址: https://gitcode.com/gh_mirrors/fo/foamFoam 是一款运行在 VS Code 之内的笔记工具它把 Markdown 文件、[[wikilink]]双向链接、图谱可视化与发布能力整合进一个本地优先local-first的个人知识管理系统。本文以仓库中 packages/foam-vscode/README.md 为主线结合 foam-vscode 扩展的源码与配置清单系统讲解它的核心功能、命令、配置项与扩展机制帮助你在 VS Code 中搭建一套可定制、可发布、可持续演进的知识库。一、Foam 是什么在 VS Code 里长出来的知识库Foam 不是一个独立应用而是一个“住在 VS Code 里的笔记工具”。它的设计有三个关键定位本地优先笔记就是磁盘上的 Markdown 文件数据完全由你掌控不依赖任何云服务基于 Markdown你可以继续使用 VS Code 里任何你喜欢的扩展拼写检查、图表、剪贴板贴图等来增强编辑体验可扩展extensibleFoam 的 API 与内部结构是开放的你可以深入集成它的内部机制来定制自己的知识库可发布借助 link reference definitions 等功能笔记可以在非 Foam 环境下如 GitHub UI、GitHub Pages保持可导航。从源码结构看foam-vscode 扩展并非“单文件玩具”它依赖 foam/core核心数据模型、解析器、图谱与查询引擎与 foam/graph-view图谱 Webview自身则负责把这两者接入 VS Code 的 API。扩展的激活入口在 src/extension.ts它依次完成日志初始化、工作区扫描include/exclude 规则、Markdown 解析器与缓存创建、图谱 bootstrap最后通过Promise.allSettled逐个激活src/vscode/features下的全部功能模块——单个功能模块失败只降级该功能不会中断整个扩展的激活。二、快速开始三步建好你的 Foam 工作区已经在用 ObsidianObsidian 的 vault 通常直接就是一个 Foam 工作区可参考仓库文档 docs/user/recipes/migrating-from-obsidian.md 迁移。官方推荐的起步方式非常直接从 foam-template 创建仓库在 GitHub 上基于foam-template模板创建仓库。如果不想公开记得把仓库设为 private。克隆并打开把仓库克隆到本地用 VS Code 打开。安装推荐扩展VS Code 弹出“推荐扩展”提示时点击Install all或者点击Show Recommendations逐条审查后安装。这一步会顺带安装 Foam 扩展本身如果你已经装过请确保更新到最新版本。用这种方法起步你会得到一套现成的.foam/目录结构存放模板、查询等、每日笔记模板、图谱视图等基础设施无需手动配置即可体验完整功能。三、核心功能详解1. 图谱可视化Graph Visualization使用Foam: Show Graph命令可以直观看到笔记之间如何通过链接连成一张网络图。命令的实现位于 src/vscode/features/graph-webview/index.tsfoam-vscode.show-graph会创建或复用并置前一个名为 “Foam Graph” 的 Webview 面板面板数据由buildGraphData(foam.workspace.list(), foam.graph.getAllConnections(), ...)生成并且监听foam.graph.onDidUpdate—— 只要笔记或链接发生变化图谱会实时刷新。点击节点时默认用vscode.open打开笔记源文件如果开启foam.graph.navigateToPreview则会改用markdown.showPreview打开 Markdown 预览。图谱还支持foam.graph.titleMaxLength节点标题超长时截断显示默认 24 字符0或负数表示不截断截断逻辑见 graph-webview/index.tsfoam.graph.style自定义节点颜色、分组规则、背景等样式foam.graph.views定义多个命名视图如Default、按目录着色、按类型着色并可通过带{ view: name }参数的键绑定打开视图配置会在 resolveViewStyle 中与foam.graph.style合并foam.graph.onStartup设为true时扩展启动即自动打开图谱。2. Foam Queries把查询“嵌入”笔记Foam Queries 允许你直接在 Markdown 预览中嵌入动态、自动更新的列表、表格和计数只需在代码块中声明foam-queryDQL 语法或foam-query-jsJavaScript 语法foam-query SELECT ... WHERE ...[](https://link.gitcode.com/i/829107ad8ae029f11003d355ea9026b7) 渲染逻辑在 [src/vscode/features/preview/foam-query-renderer.ts](https://link.gitcode.com/i/433433589cf41179e316585fb7fbfc48)它劫持 markdown-it 的 fence 规则遇到 foam-query / foam-query-js 代码块时分别调用 renderDqlQuery / renderJsQuery 渲染为 HTML出错时输出 foam-query-error 样式的错误块不影响预览整体渲染。查询中引用的笔记若含 [[wikilink]]会先被重写为相对工作区根目录的链接再渲染保证链接可点击。完整的查询语法参考见仓库文档 [docs/user/features/foam-queries.md](https://link.gitcode.com/i/e926486de27b26393fef2b3ffb099f99)。 ### 3. Block IDs链接到笔记内部的“块” [[note#^blockid]] 语法可以让你链接或嵌入一篇笔记中的**段落、列表项、标题、引用块**。用法是先在目标块元素后加一个 ^id 标记 md 这是一个可以锚定的段落。 ^my-block-id然后在知识库的任何位置用[[note#^my-block-id]]引用它。块级锚点让知识库的粒度从“篇”细化到“段”是构建精确引用关系的基础。相关实现与既有链接改写逻辑可参见 src/vscode/features/preview/wikilink-embed.ts 与文档 docs/user/features/block-anchors.md。4. 笔记嵌入Note Embed除了链接你还可以嵌入其他笔记的内容——整篇、某个章节甚至某个块都可以。结合 Block IDs 与章节支持可以在一个页面里聚合多个来源的内容形成“仪表盘式”的笔记。渲染细节由预览侧插件wikilink-embed完成src/vscode/features/preview/wikilink-embed.ts嵌入的呈现风格可通过配置foam.preview.embedNoteType控制见下文配置表。5. 链接自动补全Link AutocompletionFoam 帮助你在笔记之间以及 placeholder 之间建立连接输入[[时会弹出补全候选候选标签默认使用笔记路径也可切换为标题或标识符。相关配置foam.completion.label补全项的标签取什么属性path/title/identifierfoam.completion.useAlias何时自动使用别名never/whenPathDiffersFromTitlefoam.completion.linkFormat补全产出的是 wikilink[[note-name]]还是标准 Markdown 链接Note Name。6. 重命名时同步链接Sync links on file rename重命名文件后指向该文件的所有链接会被自动更新笔记之间的一致性得到保障。开关为foam.links.sync.enable默认true。对于标准 Markdown 链接README 建议额外开启 VS Code 内置的markdown.updateLinksOnFileMove.enabled设置两者配合效果最佳。7. 跨目录唯一标识符Unique identifiers across directoriesFoam 支持多个目录中存在同名文件。它会使用“能满足唯一性要求的最小标识符”来引用目标并且能报告并修复已有歧义的 wikilink歧义链接会被诊断标出并提供快速修复Quick Fix选择要链接的具体文件——诊断逻辑见 src/vscode/features/lint/wikilink-diagnostics.ts其中AMBIGUOUS_IDENTIFIER_CODE对应的修复会调用FoamWorkspace.getShortestIdentifier计算出最短唯一标识符并替换链接wikilink-diagnostics.ts未知章节[[note#Section]]、未知块[[note#^block]]、重复块 ID 同样会以诊断 快速修复的形式呈现UNKNOWN_SECTION_CODE、UNKNOWN_BLOCK_CODE、DUPLICATE_BLOCK_ID_CODE。8. 链接预览与导航Link Preview and Navigation把鼠标悬停在 wikilink 上即可预览目标笔记内容点击即可跳转。预览开关为foam.links.hover.enable默认true。相关实现见 src/vscode/features/navigation/hover-provider.ts 与 navigation-provider.ts。9. 跳转到定义、查看引用Go to definition, Peek ReferencesCtrlClick或对应键位可以从任意 wikilink 跳到目标笔记同时可以Peek References查看当前笔记在知识库中被哪些地方引用——这是反向链接能力的编辑器侧形态实现见 src/vscode/features/navigation/navigation-provider.ts。10. Preview 内导航Navigation in Preview在 VS Code 的 Markdown 预览面板中也可以点击 wikilink 完成导航让“渲染后的阅读态”同样具备链接能力。这依赖扩展对 markdown-it 的扩展extendMarkdownIt钩子由各 feature 模块统一向extension.ts注册。11. 章节支持Support for sectionsFoam 对笔记章节提供了完整的支持链条自动补全、导航、嵌入、诊断。语法就是标准 wiki 语法[[resource#Section Title]]12. 链接别名Link AliasFoam 支持链接别名[[wikilink]] [[wikilink|alias]]别名让引用在正文中读起来更自然同时不破坏链接的目标解析。13. 模板Templates使用自定义模板避免重复劳动Foam: Create New Template创建模板Foam: Create New Note from Template基于模板建笔记。模板目录默认是.foam/templates配置项foam.templates.folder。命令实现见 src/vscode/features/notes/create-note-from-template.ts它最终复用createNote({ askForTemplate: true }, foam)流程create-note.ts。模板里支持FOAM_TITLE、FOAM_DATE_*等变量日期变量所用 locale 由foam.dateLocale控制默认跟随系统也可用 BCP 47 语言标签如en-US、ja-JP。完整模板语法见文档 docs/user/features/templates.md。14. Backlinks 面板Backlinks Panel在资源管理器侧边栏的Connections视图中可以快速查看哪些笔记引用了当前激活的笔记每个引用都展示其所在上下文并附带笔记预览。实现见 src/vscode/features/notes/connections.ts面板监听foam.graph.onDidUpdate与活动标签页变化实时刷新工具栏支持在全部链接 / 反向链接Backlinks/ 正向链接Links之间切换并可过滤为“仅笔记”notes-only。15. Tag Explorer 面板Tag Explorer Panel用标签组织并浏览笔记Tag Explorer面板支持层级标签hierarchical tags。给笔记打标签的方式有两种——正文中写#tag或在 front matter 中声明--- tags: tag1, tag2 ---面板还提供Foam: Search Tag与Foam: Rename Tag命令重命名标签会同步更新所有引用。相关实现见 src/vscode/features/tags/完整说明见文档 docs/user/features/tags.md。16. Orphans 与 Placeholders 面板这两个面板帮助你保持知识库的健康状态Orphans孤儿笔记既没有入链也没有出链的笔记——它们游离于知识网络之外Placeholders占位符悬空链接dangling links或“有链接但没有内容”的笔记。在Orphans/Placeholders面板中集中查看并处理它们能让知识库始终处于更有序的状态。两个面板都支持“仅当前文件 / 全部工作区”与“按文件夹分组 / 平铺”切换还可以通过foam.orphans.exclude、foam.placeholders.exclude配置 glob 将特定路径排除在报告之外。相关实现见 src/vscode/features/notes/orphans.ts 与 placeholders.ts。17. 语法高亮Syntax highlightFoam 对 wikilink 与 placeholder 使用不同的高亮让你在编辑时一眼区分“已建立的链接”与“悬空链接/待创建的笔记”。这是通过注入语法实现的扩展声明了foam.wikilink.injection语法注入到text.html.markdown见 package.json语法定义在 syntaxes/injection.json。placeholder 的前景色由主题色foam.placeholder控制默认跟随编辑器的editorWarning.foreground。18. 每日笔记Daily Note用Foam: Open Daily Note默认快捷键AltD或Foam: Open Todays Note创建日记。每日笔记的命名、目录等现在通过 daily-note 模板配置旧的foam.openDailyNote.*配置项已标记为 deprecated建议迁移到模板方案详见文档 docs/user/features/daily-notes.md。还可以用Foam: Open Random Note随机打开一篇笔记适合“回顾式”浏览。19. 为 wikilink 生成引用定义Generate referencesFoam: Update Wikilink Definitions命令可以为[[wikilinks]]生成 Markdown 引用定义link reference definitions使笔记能在非 Foam 环境下使用。有了这些引用定义笔记在 GitHub UI 以及 GitHub Pages 上都能保持可导航。生成策略由foam.edit.linkReferenceDefinitions控制withExtensionswikilink 路径中保留扩展名withoutExtensions移除扩展名off关闭生成。文档见 docs/user/features/link-reference-definitions.md。四、命令参考从命令面板出发的工作流除上述功能内嵌的命令外扩展在命令面板中注册了以下主要命令完整清单见 package.json命令作用Foam: Show Graph打开/聚焦笔记图谱视图Foam: Open Random Note随机打开一篇笔记Foam: Open Todays NoteAltD打开/创建今天的每日笔记Foam: Open Daily NoteAltH打开指定日期的每日笔记Foam: Create New Note新建笔记可配合模板与Create New Note from Template使用Foam: Create New Note From Template选择模板创建笔记Foam: Create New Template新建模板文件Foam: Update Wikilink Definitions为 wikilink 生成引用定义Foam: Convert Wikilink to Markdown Link把 wikilink 转换为 Markdown 链接Foam: Convert Markdown Link to Wikilink反向转换Foam: Copy To Clipboard Without Brackets复制不带方括号的链接文本Foam: Search Tag/Foam: Rename Tag标签检索与重命名Foam: Lint Workspace (Experimental)工作区 lint 检查Foam: Clear Cache清空解析缓存Foam: Set Log Level调整日志级别Foam: Show Whats New查看版本更新说明完整命令说明见文档 docs/user/features/commands.md。五、配置参考按需定制你的知识库扩展在 VS Code 设置中暴露了以foam.为前缀的完整配置树声明于 package.json下表整理了最常用的配置项文件与范围配置项默认值说明foam.files.include[**/*]纳入 Foam 的 glob 规则可用它把范围限定到特定目录如[notes/**]或文件类型如[**/*.md]foam.files.exclude见 package.json从 Foam 中排除的 glob如**/node_modules/**/*、**/dist/**/*等排除整个文件夹用folderName/**/*foam.files.attachmentExtensionspdf mp3 webm wav m4a mp4 avi mov rtf txt doc docx pages xls xlsx numbers ppt pptm pptx视为附件的扩展名列表空格分隔foam.files.notesExtensions额外视为文本笔记的扩展名如mdx txt markdownfoam.files.defaultNoteExtensionmd新建笔记的默认扩展名foam.files.newNotePathroot新笔记创建位置root工作区根目录或currentDir当前编辑器所在目录会被模板或命令参数覆盖foam.supportedLanguages[markdown]视为 Markdown 类文档的语言列表注意修改foam.files.*系列配置后扩展会提示Reload the window使设置生效见 src/extension.ts。旧配置foam.files.ignore已废弃请改用foam.files.exclude。链接与编辑配置项默认值说明foam.links.sync.enabletrue重命名/移动笔记时自动更新 wikilinkfoam.links.hover.enabletrue悬停链接时显示笔记内容foam.links.directory.moderesolve指向目录名的链接[[bar]]如何解析resolve查找目录内的 index 文件index.ext或README.extdisabled恢复严格的文件精确匹配foam.completion.labelpath补全项标签来源path/title/identifierfoam.completion.useAliasnever何时为 wikilink 使用别名foam.completion.linkFormatwikilink补全产物格式wikilink或link标准 Markdown 链接foam.edit.linkReferenceDefinitionsoffwikilink 引用定义生成策略withExtensions/withoutExtensions/offfoam.preview.embedNoteTypefull-card嵌入笔记的渲染风格是否带标题full/content以及是否置于容器卡片中inline/cardfoam.dateLocaledefault日期变量如FOAM_DATE_DAY_NAME所用 locale可用 BCP 47 标签面板与图谱配置项默认值说明foam.orphans.exclude[]从 Orphans 报告中排除的 globfoam.placeholders.exclude[]从 Placeholders 报告中排除的 globfoam.graph.titleMaxLength24图谱节点标题最大长度超出截断0关闭截断foam.graph.style{}图谱自定义样式节点颜色、分组等foam.graph.views[]命名图谱视图名为Default的视图会在图谱无参数打开时自动应用foam.graph.onStartupfalse启动时是否自动打开图谱foam.graph.navigateToPreviewfalse点击图谱节点时打开 Markdown 预览而非源文件实验性功能与日志配置项默认值说明foam.experimentalfalse启用实验性功能AI 相似/相关笔记、导出 HTML 页面等。实验功能可能随时变更或移除foam.logging.levelinfo日志级别off/debug/info/warn/error启用foam.experimental后资源管理器中会出现Related Notes (AI)面板基于 Ollama 嵌入见 src/ai/providers/ollama/ollama-provider.ts命令面板中也会出现Foam: Show Similar Notes、Foam: Build Embeddings Index、Foam: Export to HTML page等命令。六、仓库结构读懂 Foam 的代码地图如果你想深入扩展甚至贡献代码可以按下面的路径探索本仓库根目录即 Foam 的 monorepo扩展本体packages/foam-vscode/——VS Code 扩展包含src/vscode/features/下的全部功能模块导航、预览、lint、标签、每日笔记、智能文件夹等核心引擎packages/foam-core/——数据模型model/、Markdown 解析services/markdown-parser.ts、图谱model/graph.ts、查询引擎query/含 DQL 与 JS 查询、模板系统templates/与导出export/图谱视图packages/foam-graph/——在 Webview 中渲染图谱的前端实现MCP 服务器packages/foam-mcp/——把 Foam 的图谱、搜索、标签能力暴露为 Model Context Protocol 工具CLI 工具packages/foam-cli/——提供daily、grep、links、lint、note、search、tag等命令行能力扩展激活流程src/extension.ts——展示了“核心引擎 bootstrap → 功能模块逐个注册 → 统一extendMarkdownIt聚合”的架构模式也是理解 Foam 可扩展性的最佳入口。由于扩展将extendMarkdownIt作为各 feature 的统一出口src/extension.ts预览侧的 wikilink 导航、嵌入、查询渲染、脚注等能力都是通过该钩子注入 markdown-it 的这为第三方扩展复用 Foam 的解析与渲染能力提供了稳定的集成点。七、常见问题、已知问题与版本信息已知问题Known Issues可查看仓库 GitHub Issues 页面跟踪。版本更新Release Notes见 packages/foam-vscode/CHANGELOG.md。调试日志通过Foam: Set Log Level调整日志级别输出日志帮助定位问题更详细的日志说明见文档 docs/user/tools/foam-logging-in-vscode.md。此外Foam 生态里还有大量来自社区的使用场景recipes——自动 Git 同步、从移动端记录、PDF 导出、实时协作、剪藏网页等可按需查阅 docs/user/recipes/recipes.md 寻找灵感把 Foam 塑造成适合你自己的知识工作流。【免费下载链接】foamA personal knowledge management and sharing system for VSCode项目地址: https://gitcode.com/gh_mirrors/fo/foam创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考