工具狮 (Toolion) · Markdown 编辑器
技术栈:React 19 + TypeScript + Vite + Tailwind CSS · 存储:IndexedDB / localStorage · 渲染:marked + highlight.js + mermaid
支持中英文双语 · 桌面端与移动端自适应 · 纯前端本地运行,无需后端
一、文章摘要
本文介绍一款基于 React 19 的纯前端 Markdown 笔记编辑器,全部数据存储于浏览器本地(IndexedDB + localStorage),无需联网即可使用。核心功能包括 Markdown 实时预览、17 种编程语言语法高亮、Mermaid 流程图/时序图渲染、全文笔记搜索、查找替换、文档大纲跳转、标签分类筛选、Markdown/JSON 导入导出、深浅色主题切换、中英文国际化及移动端自适应。适合前端开发者参考本地优先(local-first)应用的开发实践。
关键词:React Markdown 编辑器、本地 Markdown 笔记、marked highlight.js、Mermaid 渲染、IndexedDB 存储、React 19 前端项目、Markdown 全文搜索
二、前言
Markdown 因轻量、易读、易转换的特性,成为技术文档、知识笔记与博客写作的主流格式。市面上优秀的 Markdown 编辑器众多,但许多依赖云端同步,隐私与离线使用受限;或功能过重、加载缓慢。
本文介绍的是 Toolion 系列工具中的 Markdown 编辑器(项目地址:toolion.cn/markdown-ed… Markdown 笔记应用。经重构后,编辑器新增了代码语法高亮、Mermaid 流程图渲染、全文搜索、查找替换、文档大纲、标签分类、Markdown/JSON 导入导出、深色模式、移动端适配等多项实用功能,全部数据本地存储,无需联网即可使用。
三、核心功能全景
| 模块 | 功能点 | 说明 |
|---|---|---|
| 编辑 | 所见即所得预览 | 左侧编辑、右侧实时预览,GFM 语法支持 |
| 格式化工具栏 | 加粗、斜体、删除线、标题、引用、列表、任务列表、链接、图片、行内代码、代码块、表格、分割线 | 一键插入/包裹 Markdown 语法 |
| 代码高亮 | highlight.js | 支持 JavaScript/TypeScript/Python/Java/C/C++/C#/Go/Rust/XML/CSS/JSON/YAML/Markdown/SQL/Bash 等 17 种语言 |
| 图表渲染 | mermaid | 原生渲染流程图、时序图、类图等,随主题切换深浅色 |
| 安全 | XSS 净化 | 基于 DOMParser 的白名单过滤,移除 script/iframe 等危险标签与事件属性 |
| 笔记管理 | 新建/编辑/删除/排序 | 支持按更新时间、创建时间、标题排序,标题重复提醒 |
| 标签系统 | 标签管理、按标签筛选 | 每个标签自动着色,支持多标签 |
| 全文搜索 | 防抖搜索、命中高亮、摘要预览 | 同时匹配标题、正文、标签,结果以模态框展示 |
| 查找替换 | 查找上一个/下一个、单独替换、全部替换 | 编辑器内嵌查找替换栏,显示匹配索引 |
| 文档大纲 | H1-H6 标题大纲 | 点击大纲项直接跳转至对应行并滚动到视图中 |
| 导入导出 | 导出单个 .md、全部备份为 JSON、导入 .md、导入备份、拖拽导入 | 离线数据可完全备份与迁移 |
| 持久化 | IndexedDB + localStorage 双保险 | 自动防抖保存(1s),页面隐藏时立即持久化 |
| 主题 | 深色/浅色模式 | CSS 变量主题,支持跟随系统主题切换 |
| 国际化 | 中文 / 英文 | 界面全双语,可一键切换 |
| 快捷键 | Ctrl+B/I/K/N/F/H/S/E、Tab 缩进、智能回车 | 提升键盘党编辑效率 |
| 智能粘贴 | 代码自动识别并包裹为代码块 | 粘贴 3 行以上疑似代码时自动添加语言围栏 |
| 移动端 | 响应式布局、编辑/预览切换、侧边栏抽屉 | 适配手机与平板 |
| 统计 | 字符数、行数 | 底部状态栏实时显示 |
四、技术选型
| 技术 | 版本 | 用途 |
|---|---|---|
| React | 19.2.6 | UI 框架,函数组件 + Hooks |
| TypeScript | 6.0.2 | 静态类型检查 |
| Vite | 8.0.12 | 构建工具与开发服务器 |
| Tailwind CSS | 3.4.19 | 原子化样式 |
| marked | 18.0.5 | Markdown 解析与 HTML 渲染 |
| highlight.js | - | 代码块语法高亮 |
| mermaid | - | 流程图/时序图等图表渲染 |
| idb-keyval | - | IndexedDB 键值存储(笔记持久化) |
| react-icons (Fi) | 5.6.0 | 图标集 |
| React 19 新特性 | startTransition | 状态更新不阻塞输入,保证编辑流畅 |
五、重点功能详解
5.1 Markdown 渲染与 XSS 安全
使用 marked 解析 Markdown,并自定义 Renderer.code 处理代码块:识别 mermaid 语言围栏渲染图表,其余交给 highlight.js 语法高亮;未识别语言则按纯文本转义。
渲染后的 HTML 通过 sanitizeHtml 做白名单过滤:
- 移除
script、iframe、object、embed、form、input、button、link、meta、base等标签 - 移除
style标签(SVG 内除外) - 过滤
javascript:链接,其余外部链接自动加target="_blank"和rel="noopener noreferrer" - 移除所有
on*事件属性与srcdoc - 给
table包裹滚动容器,防止宽表撑破布局
5.2 代码语法高亮与 Mermaid 图表
注册 17 种 highlight.js 语言及其常见别名(如 js→javascript、tsx→typescript、yml→yaml、htm/html/vue→xml)。代码块高亮主题随深色/浅色模式切换,通过 CSS 变量(--hl-keyword、--hl-string 等)适配配色。
Mermaid 图表在预览阶段被提取,调用 mermaid.render 生成 SVG 替换原 <pre><code>,渲染失败时回退为高亮代码块并提示语法错误。
5.3 本地持久化(IndexedDB 优先,localStorage 兜底)
笔记数据结构:
interface Note {
id: string;
title: string;
content: string;
tags: string[];
createdAt: string;
updatedAt: string;
}
- 首次加载优先从 IndexedDB(
me-notes)读取;若为空则尝试 localStorage 迁移并写回 IndexedDB - 内容变更后 800ms 防抖写入,同时每 1s 持久化一次完整列表
pagehide事件立即强制保存,保证页面关闭时数据不丢失
5.4 全文搜索与命中高亮
标题栏与模态框均提供搜索入口,输入后 150ms 防抖触发,匹配范围包含标题、正文、标签。结果按更新时间倒序排列,命中片段通过 getSnippet 截取并用 highlightText 用 <mark> 标记,点击结果直接打开对应笔记。
5.5 查找替换与大纲
- 查找替换栏嵌入编辑器上方,支持上一个/下一个跳转、单个替换、全部替换,并显示
当前/总数索引 - 大纲面板解析
debouncedContent中的 H1-H6 标题,排除代码块内的伪标题,点击条目可定位到正文对应行并滚动
5.6 导入导出
| 操作 | 格式 | 说明 |
|---|---|---|
| 导出单笔记 | .md | 以笔记标题命名,下载纯 Markdown 文本 |
| 导出全部备份 | .json | 包含版本号、导出时间与全部笔记数组 |
| 导入备份 | .json | 去重校验,ID 冲突自动重新生成 |
| 导入 Markdown | .md / .markdown | 文件名作为标题,内容写入新笔记 |
| 拖拽导入 | 文件拖入页面 | 自动识别 JSON 备份或 Markdown 文件 |
5.7 移动端适配
720px 以下触发移动端布局:
- 顶部隐藏搜索框,改为搜索按钮弹出模态框
- 底部/顶部出现“编辑器 / 预览”分段切换,两者互斥显示
- 侧边栏变为可拉开的抽屉,配合半透明遮罩
- 输入字体自动放大至 16px,防止 iOS 双击缩放
六、核心代码片段
6.1 自定义代码渲染器(marked + highlight.js)
const markedRenderer = new marked.Renderer();
(markedRenderer as any).code = function (...args: any[]) {
let codeText = '';
let langRaw = '';
const first = args[0];
if (typeof first === 'string') {
codeText = first;
langRaw = typeof args[1] === 'string' ? args[1] : '';
} else if (first && typeof first === 'object') {
codeText = first.text || '';
langRaw = first.lang || '';
}
const lang = (langRaw || '').trim().split(/\s+/)[0].toLowerCase();
if (lang === 'mermaid') {
return `<pre><code class="language-mermaid">${escapeHtml(codeText)}</code></pre>`;
}
const validLang = lang && hljs.getLanguage(lang) ? lang : '';
let highlighted = '';
if (codeText) {
if (validLang) {
try {
highlighted = hljs.highlight(codeText, { language: validLang, ignoreIllegals: true }).value;
} catch {
highlighted = escapeHtml(codeText);
}
} else {
highlighted = escapeHtml(codeText);
}
}
const langClass = validLang || 'plaintext';
return `<pre><code class="hljs language-${langClass}">${highlighted}</code></pre>`;
};
marked.use({ renderer: markedRenderer });
6.2 防抖自动保存
useEffect(() => {
if (!isLoaded) return;
window.clearTimeout(storageTimerRef.current);
storageTimerRef.current = window.setTimeout(() => {
set('me-notes', notes).catch(console.error);
try { localStorage.setItem('me-notes', JSON.stringify(notes)); } catch { }
}, 1000);
return () => window.clearTimeout(storageTimerRef.current);
}, [notes, isLoaded]);
6.3 查找下一个与循环匹配
const findNext = useCallback(() => {
if (matches.length === 0) return;
const ta = textareaRef.current;
if (!ta) return;
const selStart = ta.selectionStart;
let next = matches.findIndex(m => m > selStart);
if (next === -1) next = 0;
setMatchIndex(next);
ta.focus();
ta.setSelectionRange(matches[next], matches[next] + findText.length);
}, [matches, findText]);
七、快速上手
7.1 环境要求
- Node.js 18+
- pnpm / npm / yarn
7.2 安装与运行
# 进入项目目录
cd apps/markdown-editor
# 安装依赖
npm install
# 启动开发服务器(默认 http://localhost:5173)
npm run dev
# 生产构建
npm run build
# 预览构建产物
npm run preview
# 代码检查
npm run lint
7.3 项目结构
apps/markdown-editor/
├── index.html
├── vite.config.ts
├── tailwind.config.js
├── postcss.config.js
├── src/
│ ├── main.tsx
│ ├── App.tsx # 主应用:编辑器、预览、侧边栏、搜索、导入导出等
│ ├── index.css # Tailwind 基础样式 + 自定义主题变量
│ ├── theme.d.ts
│ └── i18n/
│ ├── I18nContext.tsx # 双语国际化上下文
│ ├── zh.ts # 中文语言包
│ └── en.ts # 英文语言包
├── tsconfig.json
└── package.json
八、总结与展望
此次重构将 Toolion Markdown 编辑器从一个基础的写作工具,提升为一款具备代码高亮、Mermaid 图表、全文搜索、查找替换、文档大纲、标签分类、多格式导入导出与移动端适配的本地笔记应用。所有数据均存储在浏览器本地,无需后端,天然适合隐私敏感场景与离线环境。
该工具现已上线:toolion.cn/markdown-ed…