Skip to content

Use markdown-it for chat and note Markdown rendering - #178

Open
Excelius-Wang wants to merge 1 commit into
Edwardxlai:mainfrom
Excelius-Wang:feat/markdown-it-chat
Open

Excelius-Wang wants to merge 1 commit into
Edwardxlai:mainfrom
Excelius-Wang:feat/markdown-it-chat

Conversation

@Excelius-Wang

@Excelius-Wang Excelius-Wang commented Nov 18, 2026 •

Copy link
Copy Markdown

关联 Issue 与改动

将 easyread/web/js/common/markup.js 中的手写块级 / 行内 Markdown 解析替换为 markdown-it(^14.3.3),解决 AI 对话、边注卡片与笔记预览中嵌套列表、缩进续行段落、分隔线与代码块渲染异常的问题,同时完整保留 EasyRead 原有的公式、代码、论文内链、参考文献、脚注保护与 XSS 安全策略。

原有手写解析的缺陷

  1. 嵌套列表 + 缩进续行塌缩:手写 para() 通过 lines.slice(k).every(isItem) 判断列表块,当有序列表项包含缩进介绍段、嵌套子列表和结尾续行时,整块回退为普通 <p>...<br>...</p>,字面显示 2.、- 和 **...**。
  2. 分隔线与块级元素缺失:不支持 --- 水平分隔线;.cm.ai .body、.card .body、.inline-note、.np-ai-body、.np-preview 缺少 <pre> / <pre><code>、<hr>、多级嵌套列表及任务列表样式。
  3. 中文全角标点与行内强调边界:原始 CommonMark 对紧邻中文引号、括号(如 这是**“重要”**、见**(第 1 节)**)会判定为不构成强调边界。

渲染流水线

raw text
  ├─ tokens() + dedentFence()     # 前置隔离代码、围栏代码块(去除列表/引用前缀缩进)、数学公式、Markdown 链接
  ├─ maskFootnotes()              # 保护 [^n] / [^*],防止 * 破坏斜体
  ├─ prepareBlockMarkdown()       # 归一化 1、/ • 列表,拆分列表/引用内的块级公式与代码块占位符
  ├─ markdown-it (html:false, breaks:true, linkify:false)
  │    ├─ validateLink()          # 仅放行 https:// / http:// / mailto: / # 锚点
  │    ├─ scanDelims (CJK patch)  # 兼容中文全角标点旁 ** / *,不破坏 ASCII 下划线标识符
  │    ├─ er_block / er_task_list # 块级占位符与 - [ ] / - [x] 任务列表
  │    └─ renderer.rules.text     # 仅在纯文本片段内运行 blockLabel / legacyXrefs / citeLinks
  └─ restore()                    # 回填 KaTeX、<code>/<pre>、外链、内链、脚注

影响范围

  • 构建与非 editable 打包:
    • package.json / package-lock.json:将 markdown-it(^14.3.3,原本已随 markmap-lib 存在于 lockfile)显式加入 devDependencies。
    • easyread/web/src/markdown-it.js、scripts/build_note_editor.cjs:通过 npm run build:editor 打包 easyread/web/vendor/markdown-it.js 并将依赖许可证汇总到 easyread/web/vendor/note-libraries.LICENSE.txt(统一 LF 换行)。
    • easyread/web/reader.html、easyread/web/library.html:在 markup.js 前引入 /web/vendor/markdown-it.js;easyread/export/build.py 的单文件/手机版离线导出会自动内联该脚本;最小 Node VM 测试环境仍保留 fallbackInline() 兜底。
    • 关于文件长度:markup.js 由原 392 行增至 449 行,暂留在单文件内以减少额外 <script> 并兼容只加载 markup.js 的旧测试夹具;如维护者更倾向按 400 行阈值将 markdown-it 初始化拆出,可按意见再拆。
  • 样式:更新 easyread/web/css/reader-chat.css、reader.css、reader-panels.css,补齐 <hr>、<pre> / <pre><code>、嵌套 ol/ul 与 li > p 间距、.task-list-item、.md-h 标题层级及多段 blockquote p 排版。
  • 旧文献与界面文案:不改数据结构与接口,无新增用户设置项或界面文本,不影响既有 paper.json / chat.json / reader.json。
  • 回滚与波及面(Two-way door):所有公共接口(PR.md、PR.mdBlocks、PR.plain、PR.titleHtml、PR.webMathHtml、PR.unlink、PR.tex 等)签名不变,可通过回退本次引入直接恢复旧实现;主要影响调用 PR.md / PR.mdBlocks 的 AI 对话、边注卡片与笔记预览渲染。

验证结果

  • Before:在带缩进说明与子列表的嵌套编号回答(2. **...**\n 说明:\n - **子项**...\n\n---)中,整段退化为 <p>...<br>...</p>,序号/项目符号/粗体星号与 --- 原样外露。
  • After:
    • JavaScript 单元测试:node --test tests/web/test_*.cjs tests/desktop/test_*.cjs — 311 passed, 0 failed(含 tests/web/test_reader_navigation.cjs、tests/desktop/test_desktop.cjs,并更新 tests/web/test_markup.cjs 与 tests/web/test_chat_ui.cjs,覆盖嵌套列表与缩进续行、列表/引用内代码块与公式块、--- 分隔线、中文标点加粗、删除线、任务列表及 HTML/javascript: XSS 拦截;跨空行编号列表断言同步为语义化的单一 <ol>)。
    • Python 单元测试:.venv/bin/python -u -m unittest discover tests -v(macOS arm64, Python 3.12)— 676 passed(1 skipped,非 Windows 固有跳过)。
    • i18n 与格式检查:.venv/bin/python scripts/i18n_check.py 退出码 0(缺英文 0,没套 PR.t/tr 的中文 0);git diff --check 通过。
    • 非 editable 打包安装验证:使用 uv pip install --target ... --no-deps --no-build-isolation . 构建并安装 wheel 至隔离目录,在仓库目录之外启动服务,确认 /web/vendor/markdown-it.js(149,683 bytes)、/web/js/common/markup.js(22,802 bytes)及文献库首页 / 均可正常访问。
    • Electron 44 无头端到端与离线导出验证(隔离临时库):
      • 文献库进入阅读页 + 批注创建与回跳(1440×900):从 / 点击论文进入 /read/0045da470eed,划选段落新建包含嵌套列表、中文标点加粗、--- 分隔线与 Python 代码块的页边注,保存后 .card[data-note] .body 全部结构正确渲染(残留 ** 为 0);打开 #notespanel、页面滚离锚点后点击卡片,成功回跳至原段落 #b-p1-1。
      • AI 对话长文本与流式增量渲染(1440×900):右侧 问 AI 侧栏渲染真实 ReDiST 长回答(嵌套列表/子列表/缩进续行/---/引用块/15 个 KaTeX 公式与交叉引用),并按每 3 字符增量切片模拟流式 PR.mdBlocks 调用,未闭合语法阶段无异常,结束后完整结构零残留 **。
      • 窄屏溢出检查(420×840):阅读页与侧栏内容 document.documentElement.scrollWidth <= window.innerWidth,<pre> 与 .tbl-wrap 无横向撑破。
      • 离线单文件导出:easyread.export.build 生成的离线 HTML 可正常加载 PR.MarkdownIt 并解析嵌套列表与分隔线。
      • 注:仅在 Chromium 无头窗口下从 / 跳转到阅读页时观察到 1 条既有 @view-transition(library.css)在非聚焦窗口取消导航过渡的 AbortError: Transition was skipped,与本次改动无关,其余业务与渲染脚本零报错;Playwright 专项脚本(tests/browser/fixture-smoke.cjs、tests/e2e_web_offline.py)待仓库 CI 批准后执行。

Co-authored-by: Cursor <cursoragent@cursor.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant