在实际的个人知识管理或笔记工具开发中我们常常面临一个矛盾一方面我们希望笔记系统足够轻量、快速能够随手记录另一方面我们又希望笔记之间能够建立联系形成知识网络而不仅仅是孤立的文档。传统的 Markdown 编辑器擅长前者而像 Obsidian、Roam Research 这样的双链笔记工具则专注于后者但它们往往伴随着一定的学习成本和系统复杂性。Lilo 这个项目从其标题 “A tiny Markdown notes widget with a knowledge graph” 来看它试图在两者之间找到一个平衡点。它将自己定位为一个“微件”widget这意味着它可能是一个可以嵌入到其他应用或网页中的小组件核心功能是处理 Markdown 笔记并自动或手动构建知识图谱。对于前端开发者、希望为自己的博客或工具增加笔记功能的工程师或者任何想要一个极简、可定制知识管理入口的用户来说这类工具极具吸引力。本文将带你从零开始理解如何构建一个类似 Lilo 的 Markdown 笔记微件并为其集成知识图谱可视化能力。我们将涵盖从项目初始化、Markdown 解析与编辑、到图数据构建与渲染的完整流程并重点解释其中的技术选型、关键实现细节和常见陷阱。1. 理解核心概念微件、Markdown 与知识图谱在动手之前我们需要明确几个核心概念及其在本项目上下文中的具体含义这决定了后续的技术架构。1.1 什么是“微件”Widget在前端领域微件通常指一个独立的、功能完整的 UI 组件它可以被嵌入到不同的宿主页面中拥有自己的状态、样式和行为逻辑。对于 Lilo 这样的笔记微件它应该具备以下特征自包含性其 HTML、CSS、JavaScript 以及可能的构建产物如一个.js文件应该打包在一起通过一段脚本或一个标签即可引入。隔离性微件的样式应该通过作用域如 Shadow DOM 或 CSS Modules与宿主页面隔离避免样式污染和冲突。可配置性允许通过属性Attributes、Props 或初始化参数来配置例如初始笔记内容、数据存储方式、图谱布局算法等。轻量级“tiny” 意味着代码体积小加载和执行速度快对宿主页面性能影响小。1.2 Markdown 在笔记微件中的处理流程Markdown 作为输入和存储格式在微件中需要经历解析、渲染和编辑三个环节解析将 Markdown 文本转换为抽象语法树AST。常见的库有marked、remarkunified 生态、markdown-it。选择时需考虑扩展性如支持自定义语法、性能以及 AST 的易用性。渲染将 AST 转换为 HTML。可以自行遍历 AST 生成也可以使用库提供的渲染器。关键是要支持语法高亮通过highlight.js或prism和数学公式通过KaTeX或MathJax。编辑提供实时预览双栏或混合编辑或所见即所得WYSIWYG的编辑体验。可以使用CodeMirror、Monaco EditorVS Code 同款或ProseMirror来构建编辑器。1.3 知识图谱的构建与可视化知识图谱的核心是表示实体笔记、概念及其之间的关系。在笔记系统中节点通常对应一篇篇独立的 Markdown 笔记。可以从笔记标题、文件名或特定元数据如 YAML Front Matter中提取节点标签。边代表笔记之间的联系。最常见的是通过双链语法如[[笔记标题]]自动创建。边可以是有向的如引用或无向的如相关。图数据在内存中可以用一个邻接表或对象{ nodes: [], edges: [] }来表示。需要设计一个数据结构来存储节点位置、样式和边的类型。可视化将图数据渲染成可交互的图形。D3.js功能强大但学习曲线陡峭Cytoscape.js专为图论和网络分析设计API 更友好vis-network或sigma.js也是常见选择。微件场景下需要权衡渲染性能与功能丰富度。2. 环境准备与项目初始化我们将创建一个现代的前端项目使用 Vite 作为构建工具以获得快速的开发体验和优化的生产构建。2.1 开发环境要求确保你的本地环境满足以下要求项目要求检查命令Node.js版本 16 或以上推荐 LTS 版本node --versionnpm / yarn / pnpm任一包管理器即可npm --version代码编辑器VS Code 或其他现代编辑器-浏览器Chrome、Firefox 或 Edge 的最新版本-2.2 使用 Vite 初始化项目我们选择 Vanilla JavaScript 模板以保持项目的轻量和可控性。# 使用 npm 创建项目 npm create vitelatest lilo-widget -- --template vanilla cd lilo-widget # 安装初始依赖 npm install项目初始化后结构如下lilo-widget/ ├── index.html # 主页面用于开发和测试微件 ├── package.json ├── vite.config.js # Vite 配置文件 ├── public/ # 静态资源 └── src/ ├── main.js # 应用入口 ├── style.css # 全局样式 └── counter.js # 示例文件可删除2.3 安装核心功能依赖根据我们的设计安装 Markdown 处理、图谱可视化和编辑器相关的库。# Markdown 解析与渲染使用 markdown-it插件生态丰富 npm install markdown-it markdown-it-highlightjs # 代码高亮库 npm install highlight.js # 图可视化使用 Cytoscape.jsAPI 友好功能全面 npm install cytoscape # 编辑器使用 CodeMirror 6模块化现代 npm install codemirror/view codemirror/state codemirror/lang-markdown codemirror/commands codemirror/search codemirror/autocomplete # 实用工具库 npm install nanoid # 用于生成唯一ID安装后你的package.json的dependencies部分应包含这些包。3. 构建 Markdown 笔记微件核心我们将创建一个自包含的 Web Component 作为微件的基础它封装了编辑器和预览功能。3.1 创建 Web Component 骨架在src目录下创建lilo-widget.js文件。Web Component 提供了良好的封装性。// src/lilo-widget.js import { EditorView, basicSetup } from codemirror/view; import { EditorState } from codemirror/state; import { markdown } from codemirror/lang-markdown; import { highlightStyle } from ./highlight-theme.js; // 自定义高亮样式后文会创建 import MarkdownIt from markdown-it; import hljs from highlight.js; import highlight.js/styles/github-dark.css; // 引入一个高亮主题 // 定义 Markdown 解析器实例 const md new MarkdownIt({ html: true, // 允许 HTML 标签 linkify: true, // 自动将 URL 转换为链接 typographer: true, // 启用一些语言替换 highlight: function (str, lang) { // 代码块高亮处理 if (lang hljs.getLanguage(lang)) { try { return hljs.highlight(str, { language: lang }).value; } catch (__) {} } return ; // 使用默认转义 } }); class LiloWidget extends HTMLElement { constructor() { super(); // 创建 Shadow DOM 实现样式隔离 this.attachShadow({ mode: open }); // 初始 Markdown 内容可从属性获取 this._content this.getAttribute(initial-content) || # Hello Lilo\n\nStart writing...; this._editorView null; } connectedCallback() { this.render(); this.initEditor(); } render() { this.shadowRoot.innerHTML style :host { display: block; font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif; border: 1px solid #e0e0e0; border-radius: 8px; overflow: hidden; } .container { display: flex; height: 500px; } .editor-pane, .preview-pane { flex: 1; padding: 16px; overflow-y: auto; box-sizing: border-box; } .editor-pane { border-right: 1px solid #e0e0e0; background-color: #fafafa; } .preview-pane { background-color: white; } .preview-pane h1, .preview-pane h2, .preview-pane h3 { margin-top: 0; } .preview-pane code { background-color: #f5f5f5; padding: 2px 4px; border-radius: 3px; font-family: SFMono-Regular, Consolas, monospace; } .preview-pane pre { background-color: #282c34; color: #abb2bf; padding: 12px; border-radius: 6px; overflow-x: auto; } /style div classcontainer div classeditor-pane ideditor-container/div div classpreview-pane idpreview-container/div /div ; } initEditor() { const editorContainer this.shadowRoot.getElementById(editor-container); const previewContainer this.shadowRoot.getElementById(preview-container); // 初始化 CodeMirror 编辑器 const startState EditorState.create({ doc: this._content, extensions: [ basicSetup, markdown(), EditorView.updateListener.of(update { if (update.docChanged) { this._content update.state.doc.toString(); this.updatePreview(previewContainer); } }), highlightStyle // 应用自定义语法高亮主题 ] }); this._editorView new EditorView({ state: startState, parent: editorContainer }); // 初始渲染预览 this.updatePreview(previewContainer); } updatePreview(container) { // 将 Markdown 转换为 HTML const html md.render(this._content); container.innerHTML html; } // 提供获取和设置内容的方法 get content() { return this._content; } set content(newContent) { if (this._editorView) { this._editorView.dispatch({ changes: { from: 0, to: this._editorView.state.doc.length, insert: newContent } }); } else { this._content newContent; } } } // 定义自定义元素 customElements.define(lilo-widget, LiloWidget); export default LiloWidget;3.2 创建自定义语法高亮主题为了让编辑器的 Markdown 语法高亮更美观我们可以创建一个简单的主题。在src目录下创建highlight-theme.js。// src/highlight-theme.js import { HighlightStyle, tags } from codemirror/highlight; // 定义一个自定义高亮样式 export const highlightStyle HighlightStyle.define([ { tag: tags.heading1, fontSize: 1.6em, fontWeight: bold, color: #333 }, { tag: tags.heading2, fontSize: 1.4em, fontWeight: bold, color: #555 }, { tag: tags.heading3, fontSize: 1.2em, fontWeight: bold, color: #777 }, { tag: tags.emphasis, fontStyle: italic }, { tag: tags.strong, fontWeight: bold }, { tag: tags.link, color: #0366d6, textDecoration: underline }, { tag: tags.monospace, fontFamily: monospace, backgroundColor: #f5f5f5, padding: 2px }, // 可以继续为其他 tags 定义样式 ]);3.3 在主页面中测试微件修改src/main.js和index.html引入并使用我们创建的微件。首先更新src/main.js仅用于导入和注册组件如果需要。// src/main.js import ./style.css; import LiloWidget from ./lilo-widget.js; // 组件已在 lilo-widget.js 中自行注册这里只需确保导入 console.log(Lilo Widget loaded.);然后修改index.html直接使用lilo-widget标签。!doctype html html langen head meta charsetUTF-8 / link relicon typeimage/svgxml href/vite.svg / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleLilo Widget Demo/title /head body h1Lilo Markdown Notes Widget Demo/h1 pBelow is the embedded widget:/p !-- 使用自定义元素并通过属性传递初始内容 -- lilo-widget initial-content# Welcome to Lilo This is a **Markdown** note. - You can edit on the left. - See the preview on the right. javascript console.log(Hello, knowledge graph!); /lilo-widget script typemodule src/src/main.js/script /body /html现在运行开发服务器查看效果npm run dev打开浏览器访问http://localhost:5173你应该能看到一个双栏的 Markdown 编辑器左侧编辑右侧实时预览并且代码块有高亮。4. 集成知识图谱功能接下来我们将为微件添加知识图谱面板。思路是解析 Markdown 内容中的双链语法如[[目标笔记]]将其转换为图数据并使用 Cytoscape.js 进行可视化。4.1 扩展微件以包含图谱视图修改src/lilo-widget.js在 Shadow DOM 模板中添加图谱面板并引入 Cytoscape。// 在文件顶部导入 Cytoscape import cytoscape from cytoscape; class LiloWidget extends HTMLElement { constructor() { super(); this.attachShadow({ mode: open }); this._content this.getAttribute(initial-content) || # Hello Lilo\n\nStart writing...; this._editorView null; this._cy null; // Cytoscape 实例 // 简单的图数据存储 this._graphData { nodes: [], edges: [] }; } connectedCallback() { this.render(); this.initEditor(); this.initGraph(); // 初始化图谱 this.updateGraphFromContent(); // 从内容中提取图数据 } render() { this.shadowRoot.innerHTML style :host { /* 原有样式保持不变 */ } .container { display: flex; height: 600px; /* 增加高度以容纳三栏 */ } .editor-pane, .preview-pane, .graph-pane { flex: 1; padding: 16px; overflow-y: auto; box-sizing: border-box; } .editor-pane { border-right: 1px solid #e0e0e0; background-color: #fafafa; } .preview-pane { border-right: 1px solid #e0e0e0; background-color: white; } .graph-pane { background-color: #f9f9f9; } #cy { width: 100%; height: 100%; min-height: 300px; border: 1px solid #ddd; border-radius: 4px; } /* 预览样式保持不变 */ /style div classcontainer div classeditor-pane ideditor-container/div div classpreview-pane idpreview-container/div div classgraph-pane h3 stylemargin-top:0;Knowledge Graph/h3 div idcy/div /div /div ; } // initEditor 方法保持不变... initGraph() { const container this.shadowRoot.getElementById(cy); if (!container) return; this._cy cytoscape({ container: container, elements: this._graphData, style: [ { selector: node, style: { background-color: #4a90e2, label: data(label), text-valign: center, text-halign: center, font-size: 10px, width: 40px, height: 40px } }, { selector: edge, style: { width: 2, line-color: #ccc, target-arrow-color: #ccc, target-arrow-shape: triangle, curve-style: bezier } } ], layout: { name: cose, // 一个力导向布局适合知识图谱 animate: true, animationDuration: 500 } }); } updateGraphFromContent() { // 1. 提取当前笔记的标题作为当前节点 const titleMatch this._content.match(/^#\s(.)$/m); const currentNodeLabel titleMatch ? titleMatch[1].trim() : Untitled Note; const currentNodeId current; // 简化处理实际应用需唯一ID // 2. 使用正则表达式查找双链语法 [[Link]] const linkRegex /\[\[([^\]])\]\]/g; let match; const linkedNotes []; while ((match linkRegex.exec(this._content)) ! null) { linkedNotes.push(match[1].trim()); } // 3. 构建图数据 const nodes [{ data: { id: currentNodeId, label: currentNodeLabel } }]; const edges []; const seenNodes new Set([currentNodeId]); linkedNotes.forEach((noteLabel, index) { const targetNodeId note_${index}; nodes.push({ data: { id: targetNodeId, label: noteLabel } }); edges.push({ data: { id: edge_${index}, source: currentNodeId, target: targetNodeId } }); seenNodes.add(targetNodeId); }); // 4. 更新 Cytoscape 实例 if (this._cy) { // 先移除所有元素 this._cy.elements().remove(); // 添加新元素 this._cy.add([...nodes, ...edges]); // 重新运行布局 this._cy.layout({ name: cose, animate: true }).run(); } // 5. 保存图数据 this._graphData { nodes, edges }; } // 修改 updatePreview 方法在内容更新时也更新图谱 updatePreview(container) { const html md.render(this._content); container.innerHTML html; // 内容变化后重新解析链接并更新图谱 this.updateGraphFromContent(); } }4.2 处理图谱交互与笔记导航一个完整的知识图谱微件应该允许用户点击图谱节点来打开或切换到对应的笔记。这需要微件能够管理多篇笔记并处理导航事件。为了简化示例我们假设微件只管理当前笔记但可以触发一个自定义事件让宿主页面来处理导航。在initGraph方法中为节点添加点击事件监听initGraph() { // ... Cytoscape 初始化代码 ... // 添加节点点击事件 this._cy.on(tap, node, (evt) { const node evt.target; const nodeId node.id(); const nodeLabel node.data(label); // 触发一个自定义事件将点击的节点信息传递出去 this.dispatchEvent(new CustomEvent(node-selected, { detail: { id: nodeId, label: nodeLabel }, bubbles: true, // 允许事件冒泡到宿主文档 composed: true // 允许事件穿过 Shadow DOM 边界 })); // 如果是当前笔记可以高亮显示 if (nodeId current) { node.style(background-color, #f0ad4e); } }); }在宿主页面index.html中可以监听这个事件script document.querySelector(lilo-widget).addEventListener(node-selected, (event) { console.log(Node selected:, event.detail); alert(You clicked on note: ${event.detail.label}); // 在实际应用中这里可以加载新的笔记内容到微件中 // 例如widget.content fetchNoteContent(event.detail.id); }); /script5. 数据持久化与微件配置一个可用的笔记微件需要能够保存数据并且允许外部进行配置。5.1 实现简单的本地存储我们可以利用浏览器的localStorage或IndexedDB来保存笔记内容。这里以localStorage为例为每篇笔记生成一个唯一键。在LiloWidget类中添加方法class LiloWidget extends HTMLElement { // ... 已有属性 ... static get observedAttributes() { return [note-id]; // 监听 note-id 属性变化 } constructor() { super(); // ... 原有初始化 ... this._noteId this.getAttribute(note-id) || note_${Date.now()}; } attributeChangedCallback(name, oldValue, newValue) { if (name note-id newValue ! oldValue) { this._noteId newValue; this.loadNote(); } } connectedCallback() { this.render(); this.initEditor(); this.initGraph(); this.loadNote(); // 连接后加载笔记 } loadNote() { const saved localStorage.getItem(lilo_note_${this._noteId}); if (saved) { this.content saved; // 使用 setter 更新编辑器内容 } // 如果没保存过则使用初始内容或空内容 } saveNote() { localStorage.setItem(lilo_note_${this._noteId}, this._content); console.log(Note ${this._noteId} saved.); } // 可以在编辑器失去焦点或定期自动保存 setupAutoSave() { if (this._editorView) { this._editorView.dom.addEventListener(blur, () this.saveNote()); } // 或者使用防抖函数定期保存 } }5.2 通过属性与事件进行配置与通信微件应该提供清晰的 API 供外部控制。配置属性如note-id,theme(light/dark),layout(graph layout type)。公开方法如save(),load(id),getGraphData()。自定义事件如node-selected,content-changed,saved。例如在类定义末尾添加// 公开方法 save() { this.saveNote(); this.dispatchEvent(new CustomEvent(saved, { bubbles: true, composed: true })); } load(noteId) { this.setAttribute(note-id, noteId); } getGraphData() { return JSON.parse(JSON.stringify(this._graphData)); // 返回深拷贝 }6. 生产环境构建与集成6.1 构建独立 JS 包为了让微件能像普通 JS 库一样被引入我们需要配置 Vite 将其打包为一个单独的、自执行的 JS 文件UMD 或 IIFE。更新vite.config.jsimport { defineConfig } from vite; import path from path; export default defineConfig({ build: { lib: { entry: path.resolve(__dirname, src/lilo-widget.js), name: LiloWidget, fileName: (format) lilo-widget.${format}.js, formats: [umd] // 输出 UMD 格式兼容多种环境 }, rollupOptions: { // 确保不打包外部依赖或者处理为微件的一部分 // 这里我们选择将部分依赖打包进去 output: { globals: { // 如果某些库是 CDN 引入在此声明全局变量名 } } } } });运行构建命令npm run build构建完成后在dist目录下会生成lilo-widget.umd.js文件。这个文件包含了所有依赖除了配置为 external 的可以直接在浏览器中通过script标签引入。6.2 在独立 HTML 中引入微件创建一个demo.html来演示如何集成!DOCTYPE html html langen head meta charsetUTF-8 titleEmbed Lilo Widget/title !-- 引入构建好的微件库 -- script src./dist/lilo-widget.umd.js/script style body { font-family: sans-serif; padding: 20px; } .container { margin: 20px 0; } /style /head body h1My Blog Post/h1 pHere is my interactive note widget:/p div classcontainer lilo-widget note-idblog_note_1/lilo-widget /div button onclicksaveNote()Save Note/button script function saveNote() { const widget document.querySelector(lilo-widget); widget.save(); } // 监听微件内部事件 document.querySelector(lilo-widget).addEventListener(node-selected, (e) { console.log(Selected in host page:, e.detail); }); /script /body /html7. 常见问题排查与优化建议在实际开发和集成过程中你可能会遇到以下问题。7.1 微件样式与宿主页面冲突现象微件内部的样式影响了外部页面或者外部页面的样式影响了微件。原因CSS 样式泄露。解决方案确保使用 Shadow DOM在构造函数中调用this.attachShadow({ mode: open })。重置 Shadow DOM 内的样式在微件内部样式中对常用元素如div,span设置box-sizing: border-box并限制字体继承。使用 CSS 变量提供主题接口在:host中定义 CSS 变量允许宿主页面覆盖。:host { --lilo-primary-color: #4a90e2; --lilo-bg-color: white; /* ... */ } .node { background-color: var(--lilo-primary-color); }7.2 图谱节点过多导致性能下降现象当笔记和链接数量很大时图谱渲染卡顿交互迟缓。原因Cytoscape 一次性渲染过多元素布局计算耗时。解决方案虚拟化/分页只渲染当前视野内及附近的节点。聚合节点将关联紧密的节点聚类成一个超级节点。优化布局参数使用cose-bilkent布局并调整其参数如animate: endrefresh: 20以减少计算量。延迟渲染在用户停止编辑或主动触发时再更新图谱而不是每次按键都更新。7.3 双链解析不准确或复杂现象正则表达式\[\[([^\]])\]\]无法处理嵌套括号或包含]]的标题。原因正则表达式过于简单。解决方案使用更复杂的正则如\[\[([^\[\]])\]\]。更好的方法是使用 Markdown 解析器如markdown-it的 AST 来遍历和查找链接节点这更准确。markdown-it可以通过插件来处理双链语法。7.4 编辑器与预览滚动不同步现象在编辑长文档时左右两栏滚动位置不一致。解决方案监听编辑器的滚动事件同步预览面板的滚动位置比例同步。使用现有的库如codeMirror的scroll事件与预览容器的scrollTop进行映射。这是一个增强体验的功能对于最小可行产品MVP可以暂不实现。7.5 生产环境构建体积过大现象生成的lilo-widget.umd.js文件体积超过 1MB。原因引入了完整的highlight.js、cytoscape等库。优化建议按需引入highlight.js只引入需要的语言包cytoscape可能无法按需引入但可以评估是否有更轻量的替代品。使用 CDN在 UMD 构建配置中将大型库设置为external并通过script标签从 CDN 引入利用浏览器缓存。代码分割如果微件功能复杂可以考虑拆分成多个 chunk 异步加载。8. 扩展方向与最佳实践基于这个基础版本你可以从以下几个方向进行扩展使其更接近一个成熟的产品。8.1 功能扩展多笔记管理在微件内实现笔记列表、创建、删除和切换。更丰富的图谱分析计算节点中心度、社区发现、路径查找。多种图谱布局提供力导向、层次、圆形等布局算法供用户选择。离线优先与同步集成IndexedDB进行本地存储并可选配后端同步如使用PouchDB与 CouchDB 同步。插件系统允许用户通过 JavaScript 注册插件来扩展 Markdown 语法或图谱行为。8.2 工程化最佳实践单元测试为 Markdown 解析、图数据提取等核心逻辑编写测试使用 Jest 或 Vitest。类型安全使用 TypeScript 重写项目定义清晰的接口如Note,GraphNode,GraphEdge。状态管理当状态复杂时如多笔记、全局筛选引入一个轻量级状态管理方案如nanostores。可访问性为编辑器、图谱节点添加 ARIA 属性确保键盘导航友好。错误边界在微件顶层捕获并优雅地处理错误避免整个宿主页面崩溃。8.3 部署与集成清单将微件集成到其他系统前请检查以下清单检查项是/否说明样式是否完全隔离确保 Shadow DOM 启用且无样式泄露。构建产物是否独立确认单个 JS 文件是否包含所有必要依赖或正确声明外部依赖。公开 API 是否清晰属性、方法、事件是否都有文档说明是否有版本控制微件版本号是否随构建更新是否处理了浏览器兼容性目标浏览器是否支持 Web Components 和 ES6 特性性能是否可接受在包含 50 笔记和链接的场景下加载和交互是否流畅通过以上步骤我们完成了一个具备 Markdown 编辑、实时预览和知识图谱可视化核心功能的微型 Web 组件。它足够“tiny”以快速集成又通过知识图谱提供了笔记间的关联价值。在实际项目中你可以根据具体需求选择性地深化其中任何一个模块例如替换更强大的编辑器、实现更复杂的图算法或将其与你的后端笔记服务连接起来。
