README 与 Markdown 渲染 — 符号流变排版稿

为什么 Markdown 渲染重要

在 GitHub 上，README 和文档的默认展示方式是原始 Markdown 符号流——星号、井号、方括号这些标记和内容混在一起。对熟悉 Markdown 的人来说一眼能看懂结构，但大量开源项目的 README 里还有表格、代码块、图片、引用块，原始形态下手机屏幕上读起来很费劲。

Gloom 把 Markdown 直接渲染成排好版的 HTML，标题、列表、表格、代码块各司其职，像在读一篇技术文章而不是源码。

渲染支持的元素

标题层级

# 到 ###### 六级标题正常渲染，字号递减。Gloom 的 Markdown 渲染器会自动给每个标题留顶部间距，避免大段空白。

代码块

围栏代码块（\\\`lang）会根据 lang 参数自动识别语言并应用语法高亮——与代码文件的高亮效果一致，深浅色模式联动。

表格

标准 Markdown 表格正常渲染，边框和对齐方式保留。如果表格超宽（比如十几列的配置表），可以横向滚动。

图片

Markdown 里引用的图片（无论是相对路径的仓库内图片，还是远程 URL 图片）都会直接渲染成图片。图片宽度自动适配屏幕，点击可放大。

引用块

> 开头的引用会渲染成左侧竖线 + 缩进的灰色区块，区分正文。

链接

• 相对路径链接（如 docs/guide.md）：如果目标文件在仓库里，Gloom 会在应用内跳转到该文件
• 外部链接（http(s)://...）：点击后用系统浏览器打开
• 锚点链接（#installation）：跳到当前文件对应标题

任务列表

- [x] / - [ ] 格式的任务列表会渲染成带勾选框的列表，已勾选的打叉。

移动端适配细节

• 长 README 折叠：超过一定长度的 README，首次打开会折叠后半部分，需要点展开。这是为了避免首屏被 README 拉得过长，文件列表被挤到看不见
• 图片尺寸：README 里的大图自动缩放到屏幕宽度的 90%，保持比例不变形
• 内嵌 HTML：GitHub README 偶尔会有 <details> / <summary> 折叠标签、<img> 等内嵌 HTML，Gloom 的渲染器会尝试兼容

相对路径的一个坑

如果 README 里有 ./docs/guide.md 这种相对路径，而目标文件实际上不存在（或者路径不对），Gloom 在点击时会提示「找不到文件」。这不是 Gloom 的问题，而是仓库 README 本身的链接失效——GitHub 网页版也一样。