开发者工具集
返回 网站动态
DevTool 团队

README.md 在线预览：提交 GitHub 前检查 GFM 排版

提交 GitHub 前如何在线预览 README.md？用这份清单检查标题结构、GFM 表格、任务列表、代码块、相对链接、图片、Mermaid 与移动端排版。

README 预览的目标是减少提交后的意外

README.md 往往是项目的第一份使用说明。用户会从这里判断项目是什么、如何安装、怎样运行、遇到问题去哪找。源码中的一个小错误，例如未闭合的代码围栏或失效的相对图片，会直接影响第一印象和操作成功率。

在提交前用Markdown 在线阅读器打开 README，可以并排检查源码和渲染结果。它适合发现通用 Markdown 与 GFM 排版问题；仓库路径、徽章服务和 GitHub 专属行为则需要在目标平台再确认一次。

一份可扫描的 README 应该怎样组织

没有适合所有项目的固定模板，但大多数开发者工具可以按下面的阅读顺序组织：

  1. 项目名称和一句明确说明；
  2. 可选的状态徽章和真实产品截图；
  3. 安装要求与最短安装命令；
  4. 一个可以复制运行的最小示例；
  5. 配置、常见用法与限制；
  6. 测试、贡献、许可证和支持渠道。

标题层级应形成连续结构。README 通常已有一个 H1，后续使用 H2 和 H3，不要为了视觉大小直接从 H2 跳到 H4。在线预览时打开目录，可以快速发现层级是否混乱或标题是否过长。

提交前的 GFM 检查清单

表格

检查表头分隔行、竖线数量和窄屏表现。内容较长时，列表通常比六七列的大表格更易读。表格单元格内换行和复杂 HTML 的结果可能因平台不同而变化。

任务列表

使用 - [ ] 与 - [x]，并确保前面有空格。任务列表适合路线图和完成状态，但不要把关键安装步骤做成看起来可点击、实际不可操作的复选框。

代码块

每个围栏代码块应闭合并标注正确语言。命令示例不要包含 shell 提示符，否则用户复制时还要删除。分别标明 Bash、PowerShell 或其他平台差异，避免把多套命令混在同一个代码块里。

npm install
npm run dev

链接与图片

相对链接的解析位置取决于 README 所在目录和查看页面。./docs/setup.md、../assets/demo.png 在本地预览器中缺少仓库基准地址时可能无法显示，但在 GitHub 上有效；反过来，依赖本机绝对路径的链接在提交后一定失效。

提交前可逐项确认：

  • 文件名大小写与仓库完全一致；
  • 图片使用仓库相对路径或稳定的 HTTPS 地址；
  • 标题锚点在改名后同步更新；
  • 外部链接没有指向登录后才可见的页面；
  • 图片有简短、具体的替代文本。

Mermaid、数学公式和 HTML 的兼容性

GitHub 支持多种 GFM 语法，也支持特定 Mermaid 代码块，但 npm、PyPI、公司内部文档站或其他 Git 托管平台的能力可能不同。KaTeX 数学公式、GitHub Alerts、脚注和 emoji 同样需要按发布目标验证。

原始 HTML 的差异尤其明显。出于安全原因，预览器和平台通常会移除脚本、事件属性或危险标签。本站阅读器默认不解析内嵌 HTML，可避免预览不可信 README 时执行内容，但这也意味着依赖 <details> 或复杂 HTML 表格的页面不会完全复刻 GitHub。

更完整的语法边界可参考Markdown 在线预览兼容性指南。

用真实读者任务检查内容

排版没有报错，不代表 README 已经完成。按第一次接触项目的读者视角完成一次任务：

  1. 只阅读首屏，能否说清项目用途和适用对象？
  2. 从空目录开始，安装命令是否包含必要前提？
  3. 复制最小示例，是否能得到文档描述的结果？
  4. 配置项是否说明默认值、是否必填和敏感信息处理方式？
  5. 失败时是否能找到故障排查、issue 模板或支持入口？

这些验证不能由 Markdown 渲染器代替，但在线预览可以让说明结构和命令边界更容易检查。

在桌面和手机宽度下各看一次

README 的访问者不一定使用桌面电脑。切换窄窗口后重点观察：

  • 超长项目名、URL 和无法换行的命令；
  • 表格是否造成整页横向滚动；
  • 大图是否有合理尺寸；
  • 徽章过多时是否挤占主要信息；
  • 目录和长列表是否仍能快速扫描。

不要为了让桌面布局整齐而使用大量空格手工对齐。Markdown 的价值在于结构可跨设备重新排版。

隐私与外部资源

本站阅读器选择的本地 README 和粘贴文字在浏览器内处理；主动加载 raw URL 时会请求对应远程主机。页面中的外部图片或链接也可能在最终平台产生第三方请求，因此示例中不要嵌入带用户标识的追踪地址。

分享链接虽然把正文放在 URL fragment 中、不把 fragment 发送给本站服务器，但完整链接仍可能保存在历史记录或被接收者转发。含私有仓库信息、密钥和内部域名的 README 不应通过分享链接传播。

推荐的提交顺序

  1. 在本地完成内容和命令验证。
  2. 用在线阅读器检查通用 GFM 排版、目录、代码块和窄屏表现。
  3. 运行仓库已有的 Markdown lint、链接检查或文档构建。
  4. 推送分支后，在 GitHub 的最终渲染页面核对相对资源和平台扩展。
  5. 让一位不了解项目的人按 README 完成最小任务，记录真正卡住的位置。

还没有合适的打开方式时，可先阅读Windows、macOS 和手机打开 .md 文件的方法。准备好文件后，直接在线预览 README.md。