# @conql/codemirror-live-markdown

基于 CodeMirror 6 的 Markdown 实时预览编辑器库，交互参考 Obsidian。Markdown 文本始终是唯一数据源，预览和编辑通过正式的 CodeMirror 扩展实现。

[English](README.md) | 简体中文

1.0.0 是基于 blueberrycongee 原始库独立维护的 fork 版本。参见 [迁移说明](docs/MIGRATION.md) 和 [宿主接入示例](docs/INTEGRATION.md)。

## 安装

```bash
npm install @conql/codemirror-live-markdown
```

## 本地体验

在仓库根目录运行：

```bash
npm ci --include=dev
npm run demo
```

打开 http://localhost:5173。Demo 支持单篇笔记、本机浏览器保存、大纲、搜索、Markdown 导出、实时预览／源码／只读模式和亮暗主题。它不提供文件库或附件存储服务。

要在其他项目验证本地修改，先在本仓库执行 `npm pack`，再到宿主项目安装生成的 `.tgz`。`prepare` 会为打包和 Git 安装生成 ESM、CommonJS 和类型声明。

CodeMirror、Lezer 是 peer dependencies，新版 npm 会自动安装必需的 peer。公式和代码高亮按需安装：

```bash
npm install katex lowlight
```

## 最小接入

```typescript
import { EditorView } from '@codemirror/view';
import { liveMarkdown, initHighlighter, initMathRenderer } from '@conql/codemirror-live-markdown';
import 'katex/dist/katex.min.css';

await Promise.all([initHighlighter(), initMathRenderer()]);

const view = new EditorView({
  doc: '# 开始写作\n\n这里是 **正文**。\n\n- [ ] 一个待办事项',
  parent: document.querySelector('#editor')!,
  extensions: [liveMarkdown()],
});
```

未安装可选渲染器时，删除对应初始化和 CSS 导入。代码会回退到普通文本；不需要公式预览时设 `math: false`。不再需要宿主手动维护 document 上的拖选监听。

## 本轮具备的功能

| 范围 | 功能 |
| --- | --- |
| 编辑基础 | 三种显示模式、代码原位编辑、原生选区、组合输入期间的装饰映射 |
| 常用排版 | 标题、粗斜体、删除线、行内代码、分隔线、引用、列表悬挂缩进、任务复选框 |
| 笔记语法 | `==高亮==`、`%%注释%%`、标签、Wiki 链接与别名、可折叠 Callout、脚注跳转、frontmatter 识别 |
| 公式 | `$…$`、多行 `$$` 块、兼容旧反引号公式和 math 围栏；可选 KaTeX／自定义渲染器 |
| 表格 | 单元格编辑、Tab／Shift-Tab／Enter 导航、增删行列、对齐、粘贴 TSV 网格、事务撤销 |
| 写作工具 | 格式命令、查找替换、基础折叠、大纲提取、静态／异步 Wiki 目标补全 |
| 宿主接口 | 内链打开回调、图片路径解析、Wiki 图片尺寸、粘贴／拖入附件保存、按需代码围栏渲染 |
| 视觉 | 亮暗主题、统一颜色与边距、窄屏写作 demo |

Frontmatter 目前保留源码编辑。笔记／块嵌入、属性面板、Vault、反链、同步、插件市场尚未实现；文件索引和持久化由宿主负责。Wiki 目标里的 `#标题`、`#^块` 会交给宿主解析。

## 配置

```typescript
liveMarkdown({
  mode: 'live', // 'live' | 'source' | 'reading'
  theme: 'light', // 'light' | 'dark' | false
  codeBlocks: { interaction: 'inline', lineNumbers: false },
  tables: 'editable', // 'editable' | 'preview' | false
  math: true,
  images: { maxWidth: '100%', showAlt: true },
  wikiLinks: [{ target: '写作计划' }],
  links: { onWikiLinkClick: target => openNote(target) },
});
```

`openNote` 由宿主提供。`codeBlocks`、`images`、`links` 也接受 `false`。附件保存和 Mermaid 等围栏渲染通过 `attachments`、`codeRenderers` 显式接入，详见 [示例](docs/INTEGRATION.md)。

预设包含 Markdown parser、历史、搜索、折叠与快捷键。已有 CodeMirror 编辑器可继续组合独立插件；不要重复安装表格或代码渲染器。`keybindings: false` 会一起省略预设中的历史、搜索、折叠和编辑快捷键。

代码块支持 `inline`（预设默认）、`auto`（独立插件默认，光标进入时显示源码）、`toggle`（MD／Code 按钮切换）。未闭合围栏保持可编辑。预设的 reading 模式会禁用编辑；单独使用模式 facet 只影响呈现。

常用快捷键：Ctrl／Cmd + B 加粗、I 斜体、E 行内代码、K 插入链接、Shift + H 高亮、Enter 切换任务、F 查找。还导出了删除线、插入表格、大纲等函数，完整出口见 [src/index.ts](src/index.ts)。

主题变量接受完整 CSS 值：

```css
#editor {
  --md-font: system-ui, sans-serif;
  --md-code-font: ui-monospace, monospace;
  --md-font-size: 16px;
  --md-padding: 24px;
  --md-accent: #6751c7;
  --md-code-bg: rgba(80, 90, 110, .055);
}
```

深色使用 `theme: 'dark'` 或独立的 `darkEditorTheme`。外层阅读宽度和滚动容器由宿主设置。

## 开发与验证

```bash
npm run typecheck
npm run typecheck:demo
npm run lint
npm test
npm run build
npm run build:demo
npx playwright install chromium
npm run test:e2e
```

可以用 `CHROME_PATH=/path/to/chrome` 运行本机浏览器。启动 demo 后运行 `node scripts/capture.mjs` 可生成桌面／窄屏截图和长文档测量。失败截图与 trace 保存在 `test-results/`。

自动化的组合输入与窄屏测试不等同于真实系统输入法、触控和屏幕阅读器验收。剩余边界与手工检查见 [路线图](ROADMAP.md) 和 [贡献指南](CONTRIBUTING.md)。

## 许可

[MIT](LICENSE)。基于 blueberrycongee 的原始库，使用 CodeMirror 6 与 Lezer，交互参考 Obsidian。