Skip to content

Issue 119

Jump to bottom
clean edited this page Sep 29, 2026 · 2 revisions

Issue #119：Markdown 文件支持 Preview 渲染预览

背景与问题

文件视图原先将 README 等 Markdown 文档作为源码显示，阅读时无法直接看到标题、列表和表格的排版效果。本次为仓库文件增加只读 Preview，同时保留完整源码入口。

目标与范围

  • .md 扩展名大小写不敏感，默认使用 Preview，当前仓库会话内记住源码/Preview 选择。
  • 支持标题、段落、强调、列表、引用、分隔线、链接、图片、行内代码及代码块，以及 GFM 表格、删除线和只读任务列表。
  • 本地与 SSH 仓库都读取当前工作区文件；刷新同步更新文档和相同路径的图片。
  • 沿用文件读取、空文件、权限错误和超限提示。切换模式只改变显示，不编辑文件或暂存区。
  • 不包含编辑保存、渲染后的 Diff、MDX 执行、Mermaid 或数学公式。

方案与取舍

FilesView 继续通过现有目录/文件接口读取内容并取消过期请求。Markdown 文件在 CodeView 和新增 MarkdownPreview 之间切换，使用已安装的 react-markdown 与 remark-gfm，无需新增依赖或服务端接口。目录树、选中文件和会话状态沿用原有机制。

代码块按文本保留 Markdown 字符，不再次解析。标题生成包含中文的文档锚点，重复标题使用独立后缀。预览使用现有主题变量；长代码块和表格在各自区域横向滚动，图片保持比例并限制宽度。Markdown 超过 256 Ki 字符时暂停渲染并提示切换源码，服务端 1 MiB 文本/5 MiB 图片读取上限继续有效。

资源处理规则：

输入 行为
相对文件路径 以当前文档目录为基准；解码并规范化后通过仓库只读接口访问
以 / 开头的路径 以当前仓库根目录为基准，不访问系统绝对路径
仓库内文档链接 在文件视图打开，展开父目录并同步选中；可带标题锚点
#标题锚点 在当前文档内跳转；不存在时给出提示
路径查询参数 不参与仓库文件定位；文件名中的 ?、# 可用 URL 编码
仓库图片 支持 PNG、JPEG、GIF、WebP；缺失、损坏、超限、符号链接或不支持的格式显示原因
HTTP(S) 链接 在外部浏览器或新标签页打开，带 noopener noreferrer
HTTP(S) 图片 默认显示说明，点击“加载外部图片”后请求，不发送 Referer
越界路径、.git、危险协议、原始 HTML 拒绝资源访问或忽略 HTML，不执行脚本；保留可理解的文本/图片回退

不改变现有仓库权限边界。Markdown 路径解析不使用应用地址作为基准；仓库图片请求沿用认证和 SSH 读取机制。外部图片加载按钮阻止冒泡，避免点击嵌套在链接中的图片占位符时意外打开链接。

验收标准

  • README 等 .md/.MD 文件能显示排版后的文档并切回完整源码。
  • 反复切换模式保留选中文件，不写入文件；返回文件视图保留会话选择。
  • GFM 表格、只读任务列表、引用、代码块正确渲染；混合列表保留普通项目符号。
  • 相对链接、中文锚点和图片有明确规则；无效图片不阻塞正文。
  • 浅色、深色和窄窗口可读，长代码、表格及宽图片不撑破内容区域。
  • 本地与真实 SSH 文件读取、刷新、相对资源和快速切换可用。
  • 空白、空文件、渲染超限、读取超限、读取失败及非 Markdown 文件有对应展示。

验证记录

环境：macOS 15.5 / arm64，Node.js 25.5.0，ego-browser Chromium；日期：2026-09-29。

代码阶段 / 检查 命令或场景 结果
首次实现 npm test -w web 165 项通过；覆盖 Markdown 渲染、资源规则与现有文件视图
同步最新 development 后，8775389 npm test -w web 177 项通过，无跳过或失败
8775389 构建 npm run build -w @alune/shared、npm run build -w @alune/ssh-client、npm run build -w server、npm run build -w web 均通过；Vite 保留现有的大 chunk 提示
提交规范与差异 npm run commitlint -- --last --verbose、git diff --check 通过
首次实现浏览器验收 源码往返、只读任务列表、相对文件/中文锚点、图片缺失/损坏/符号链接/外部加载失败、危险输入、快速切换、空文件与超限、失败重试 通过；模式切换后临时仓库内容摘要和 Git 状态未变化
首次实现刷新验收 本地及真实 SSH 文档刷新、同路径图片内容/尺寸变化 通过；更新的文档和图片均显示最新内容
8775389 复验与截图 本地源码/Preview 切换、文件不变、真实 SSH 相对文档与图片、390px 窄窗口、深浅主题 通过；截图见下方
Windows/Linux 原生桌面及发行包 未手动运行 本次使用 macOS 浏览器和本机真实 SSH/SFTP fixture；不宣称已完成跨平台原生桌面验收

复验入口为代码仓库中的 apps/web/tests/markdown-preview-fixture.cjs。构建上述工作区后运行 node apps/web/tests/markdown-preview-fixture.cjs，会输出独立的本地/SSH 页面和测试控制地址。文件、Git 仓库及 SQLite 数据均位于临时目录，退出时清理。

界面对照

以下截图均采自 8775389 的隔离测试仓库。源码图用于对照此前仅显示 Markdown 源码的阅读方式，采集自本次实现保留的源码模式，并非旧版本截图。

源码模式 浅色 Preview
Alune Markdown 源码模式 Alune Markdown 浅色预览

Alune Markdown 深色预览

Alune SSH 仓库在 390px 窄窗口中显示代码、宽表格与图片

风险、未决事项与回退

SVG 等额外图片格式、HTML、MDX、Mermaid 和公式不在支持范围。外部图片由用户主动加载，加载失败时显示说明。较大 Markdown 保留完整源码但不进行富文本渲染。显示偏好仅在仓库会话内记忆，不新增磁盘持久化或数据库迁移。

回退本次代码提交可恢复原来的源码浏览行为；本次操作不会修改用户文档。Wiki 与代码使用独立历史，回退代码时需要单独核对 Wiki 状态。

关联资料

设计文档首页 · Alune 品牌说明 · 维护约定 · 代码仓库

Alune

Clone this wiki locally