开发工具CLI文档【免费下载链接】gripPreview GitHub README.md files locally before committing them.项目地址https://gitcode.com/gh_mirrors/gr/grip点击查看免费下载grip 是一个在本地直接渲染 GitHub README 的命令行预览工具而tests/input/gfm-test.md正是 grip 团队用来拷打渲染引擎的 GFMGitHub Flavored Markdown全特性测试样本。本文以该样本为主体逐节拆解它所覆盖的 Markdown 语法与 GitHub 扩展特性并结合 grip 渲染器源码、patcher 补丁逻辑 与 测试用例 说明这些特性在 grip 中的实际渲染行为与验证方式。读完本文你将掌握 GFM 语法检测的关键清单并理解 grip 如何在本地还原 GitHub 的渲染效果。一、gfm-test.md 是什么grip 渲染引擎的考纲gfm-test.md 是一份专门为渲染器准备的测试文档文件头明确写道它包含用于测试渲染器的 GitHub Flavored Markdown 的全部特性contains all the features of GitHub Flavored Markdown for testing a renderer with特性来源涵盖经典 Markdown 语法规范与 GFM 官方扩展并附有一组一次性用例one-offs。它与同目录下的 simple.md仅含一个带 Unicode 符号的标题和一句话、zero.md 形成由浅入深的测试梯度simple.md与zero.md验证最基本、最小的渲染路径gfm-test.md则系统性覆盖语法面任何渲染器只要跑通它就基本具备了完整的 GFM 兼容能力。因此这份文档不仅是测试输入更是任何想验证 Markdown 渲染正确性无论是否基于 grip都可以直接复用的语法兼容性检测清单。二、gfm-test.md 在 grip 测试体系中的角色grip 的测试体系中一份输入对应三套基线输出分别覆盖 GitHub 的三种渲染语义输入输出tests/output/目录对应渲染模式gfm-test.mdraw/gfm-test.htmlmarkdown/raw模式GitHub 仓库 README 渲染gfm-test.mdraw/gfm-test-user-content.htmlmarkdown模式GFM、user-content如评论、Issue 正文gfm-test.mdraw/gfm-test-user-context.htmlmarkdown模式 contextjoeyespo/grip带仓库上下文的引用解析此外还有renderer/与app/两套由补丁处理patch后的中间产物tests/output/renderer/gfm-test.htmlGitHubRenderer渲染后再经 patcher.py 修补的完整页面内容tests/output/app/gfm-test.html经过GripFlask 应用整页渲染、注入样式的最终 HTML可在tests/test_api.py的test_app中看到它被用作整页比对基线。2.1 三种渲染模式在源码中的实现差异源于 GitHubRenderer 对 GitHub Markdown API 两种端点的选择if self.user_content: url {0}/markdown.format(self.api_url) # /markdownGFM 模式 data {text: text, mode: gfm} if self.context: data[context] self.context # 仓库上下文用于引用解析 data json.dumps(data, ensure_asciiFalse).encode(utf-8) headers {content-type: application/json; charsetUTF-8} else: url {0}/markdown/raw.format(self.api_url) # /markdown/rawREADME 模式 data text.encode(utf-8) headers {content-type: text/x-markdown; charsetUTF-8}对比两份基线输出可以直观看到两者差异raw 模式保留文档内的硬换行不自动加br而 user-content 模式会把段落内单个换行转换为br。例如同一段引言在 raw/gfm-test.html 中换行原样保留在 raw/gfm-test-user-content.html 中则变成br标签——这正是仓库 README与评论/Issue在 GitHub 上的真实行为差异。2.2 测试如何消费这份样本test_github.py 把 gfm-test.md 作为外部假设测试标注pytest.mark.assumption的输入它直接调用 GitHub 公共 API断言当前 API 的渲染结果与仓库内基线完全一致pytest.mark.assumption def test_github_readme(input_markdown, output_readme): assert GitHubRenderer(rawTrue).render(input_markdown) output_readme而 tests/mocks.py 中的GitHubRequestsMock则用同样的映射关系拦截 HTTP 请求使无网络的单元测试如tests/test_api.py中的test_github_renderer也能基于 gfm-test.md 完成渲染比对。当 GitHub 端渲染规则变化时tests/regenerate.py 提供了一键再生所有基线输出的脚本regenerate_raw()、regenerate_renderer()、regenerate_app()分别对应三套产物。三、Markdown 基础语法覆盖详解以下逐节对应 gfm-test.md 的原始章节说明每种语法在样本中的用例设计以及对应的渲染结果依据。3.1 内联 HTML样本同时测试了块级 HTML 与行内 HTML块级直接嵌入table并明确指出块级 HTML 标签内部的 Markdown 格式化语法不会被处理——*emphasis*保持字面星号行内span、cite、del可以出现在段落、列表项、甚至标题内部并说明用户可以选择用 HTML 的a、img代替 Markdown 的链接与图片语法。基线输出见 raw/gfm-test.html验证了table原样输出、span/del透传值得注意cite在 raw 模式下被剥离白名单行为而span/del保留这与 GitHub 的 HTML 标签过滤策略一致。3.2 特殊字符自动转义样本覆盖三类转义场景HTML 实体copy;渲染为©裸与尖括号ATT与4 5被转义为ATamp;T、4 lt; 5GFM URL 自动链接的边界由于 autolinking不会转换amp;因此...num30q...与...num30amp;q...会生成 href 不同、但显示相同文本的两个链接。基线的输出证实了这一点两条链接的href分别为...num30amp;q...与...num30amp;amp;q...。3.3 段落与换行样本用四组句子演示换行语义的层级普通段落之间以空行分隔单个换行无空行——继续同行一个br /——换到下一行两个br /、以及段落间两个br /——分别向下偏移两行、三行。从基线可见 raw 模式对源码换行原样保留而 user-content 模式会补充br这正是上一节提到的模式差异两种模式对显式br /均正常处理。3.4 标题Setext 与 atx 两种风格样本覆盖 Markdown 全部两种标题语法Setext 风格下划线生成 H1-下划线生成 H2atx 风格#到######共六个级别并特别加入一个 Unicode 用例###### This is an H√36H6 标题用于验证非 ASCII 内容的锚点生成。基线中每个标题都带有user-content-前缀的锚点与 octicon-link 图标raw 模式这正是 GitHub README 页面的标志性结构。3.5 引用块样本覆盖四种引用块形态每行都加的email 风格多段落引用只在首行加的硬换行段落引用引用嵌套引用blockquote-in-a-blockquote引用块内嵌其他 Markdown 元素标题、有序列表、缩进代码块。基线输出验证了嵌套生成嵌套blockquote引用内的标题生成了带锚点的h2缩进代码生成precode。3.6 列表等价性测试与嵌套这是样本中篇幅最大的语法区设计了多组等价性断言三种无序列表符号*、、-渲染结果一致三种有序列表写法1.递增编号、1.重复编号、3./1./8.乱序编号——基线显示乱序写法会保留起始数字ol start3但后续编号被规范化为递增两种多段落长列表缩进 vs 不缩进续行结果一致空行分隔的列表项会升级为段落内嵌列表lipBird/p/li列表项内的双段落、列表项内嵌引用块、列表项内嵌缩进代码块意外列表1986. What a great season.会被误判为有序列表ol start1986而用反斜杠转义1986\.则可阻止这种误判。最后一个用例非常实用在 README 中以数字加句点开头写年份/编号时必须用\.转义这正是 GFM 与普通 Markdown 的经典差异。3.7 代码块样本覆盖三种代码块形式四个空格缩进的标准代码块普通文本、AppleScript、含与的 HTML 片段行内code标签包裹的代码块pre标签包裹的代码块。基线显示代码块内容中的、、会被自动转义lt;div classfootergt;、amp;copy;确保原样展示。3.8 水平分割线* * *、***、*****、- - -、---------------------------------------五种写法全部渲染为hr——基线中连续输出了 5 个hr。3.9 链接内联与引用式样本完整覆盖 Markdown 两种链接风格内联式带title属性的、不带 title 的、相对路径/about/的引用式[text][id]标准写法、[text] [id]带空格分隔的写法以及 5 组缩写引用[foo 1][]等与 5 种引用定义形式双引号/单引号/圆括号 title、url尖括号包裹、换行续行的 title。基线中一个值得注意的行为This is [an example] [id] ...方括号间带空格不会合并成引用而是把[id]解析为引用链接文本、前面的[an example]保持字面量。3.10 强调覆盖单星号/单下划线的*em*/_em_、双星号/双下划线的**strong**/__strong__、词内强调un*frigging*believable基线输出unemfrigging/embelievable以及用反斜杠转义得到字面星号\*this text ...\*的用例。3.11 行内代码覆盖单反引号代码段、双反引号包裹含字面反引号的文本There is a literal backtick () here. 、反引号定界字符串、HTML 标签转义以及 HTML 实体—与—在代码段中的处理。3.12 图片覆盖四种图片写法普通内联图、带 title 的图、引用式![Alt text][img]图、原生img标签并附加width/height属性的图。基线显示 GFM 会为图片自动添加stylemax-width:100%;并包裹一层可点击放大的链接raw 模式带target_blankuser-content 模式带relnoopener noreferrer。3.13 自动链接http://joeyespo.com/生成普通链接joejoeyespo.com生成mailto:链接。3.14 反斜杠转义样本覆盖 12 类可转义字符\*、\\、\、\_、\{\}、\[\]、\(\)、\#、\、\-、\.、\!。基线输出确认转义后全部按字面文本渲染。四、GitHub Flavored Markdown 扩展特性gfm-test.md 的 GFM 区段针对 GitHub 特有的 7 类扩展逐一设置用例。4.1 词内多下划线wow_great_stuff保持原样输出。GFM 不会像某些实现那样把词内下划线误判为强调。4.2 URL 自动链接裸 URLhttp://joeyespo.com被自动包装为链接。这是 GFM 的招牌特性之一在 OfflineRenderer 中通过UrlizeExtension()扩展在本地渲染时复刻。4.3 删除线~~Mistaken text.~~渲染为delMistaken text./del。4.4 围栏代码块function test() { console.log(notice the blank line before this function?); }不使用缩进而用 围栏的代码块基线输出为precode.../code/pre。4.5 语法高亮样本用四种语言标签验证高亮行为print(Hello!)console.log(JavaScript!);python生成div classhighlight highlight-source-python内部是pl-en/pl-s等 GitHub 高亮 token 类javascript与js都映射到highlight-source-js无法匹配的语言unmatched_language退化为普通pre langunmatched_languagecode不加高亮 class。这组用例精确对应 GitHub 的语言映射表与未知语言降级策略。4.6 表格样本覆盖表格的 5 种写法几乎对应 GFM 表格规范的全部边界无前后竖线的最简写法前后带竖线Pipes的写法单元格数量不对齐Unmatched的容错写法单元格内嵌套 Markdown~~Display the~~删除线、_Closes_强调——基线显示内部 Markdown 被正确渲染对齐语法:---左对齐、:---:居中、---:右对齐分别生成alignleft、aligncenter、alignright的th/td属性。注意Text right below a table.这一行因为没有竖线被当作表格第一列内容吸入了表格td alignleft这正是表格解析到下一非表格行或空行为止的行为。4.7 HTML样本在此处留了一个*TODO: Test all allowed HTML tags.*标记说明该项目有意保留该用例作为后续补充项——结合 README.md 中样式与渲染直接来自 GitHub的设计这也解释了为什么 grip 无需自行维护 HTML 白名单GitHub API 已代劳。五、GitHub 专属写作语法Writing on GitHub5.1 换行Roses are red Violets are Blue两行之间只有单个换行无空行、无br。与 3.3 节呼应在 raw 模式下它们属于同一段落且不换行显示在 user-content 模式下会自动补充br实现换行。这是README 文件与评论/Issue 文本框语义差异的直接体现。5.2 任务列表- [x] mentions, #refs, [links](), **formatting**, and deltags/del are supported - [x] list syntax is required (any unordered or ordered list supported) - [x] this is a complete item - [ ] this is an incomplete item以及嵌套任务列表- [ ] a bigger project下挂三个子任务。注意在 raw/gfm-test.html 基线中任务框保持[x]/[ ]字面文本——GitHub Markdown API 本身不渲染任务列表。grip 通过 patcher.py 的正则补齐INCOMPLETE_TASK_RE re.compile(rli\[ \] (.*?)(ul.*?|/li), re.DOTALL) INCOMPLETE_TASK_SUB (rli classtask-list-item rinput typecheckbox classtask-list-item-checkbox disabled \1\2) COMPLETE_TASK_RE re.compile(rli\[x\] (.*?)(ul.*?|/li), re.DOTALL) COMPLETE_TASK_SUB (rli classtask-list-item rinput typecheckbox classtask-list-item-checkbox checked disabled \1\2)即把li[x] .../li/li[ ] .../li替换为带task-list-item样式的禁用复选框从而在浏览器中还原 GitHub 的任务列表外观。源码注释明确说明这是等待 GitHub API 原生支持之前的补丁方案。5.3 引用References样本覆盖 GitHub 的全部 7 种引用形式SHAdbcd7a410ee7489acf92f40641a135fbcf52a768UserSHAjoeyespodbcd7a41...User/RepositorySHAjoeyespo/gripdbcd7a41...#Num#135GH-NumGH-135User#Numjoeyespo#135User/Repository#Numjoeyespo/grip#135在基线的 raw 输出中这些保持为纯文本该组用例主要验证API 不会破坏这些文本而启用--user-content --contextjoeyespo/grip时对应 tests/output/raw/gfm-test-user-context.htmlGitHub API 会依据仓库上下文把#135、joeyespo/grip#135之类解析为指向 Issue/PR/提交的链接——这正是 GitHubRenderer 在data[context]中传递仓库参数的作用。六、从源码看渲染差异raw 与 user-content 模式综合上文可以总结出 gfm-test.md 在 grip 中的完整数据流gfm-test.md │ ├─ GitHubRenderer(rawFalse) ── POST /markdown/raw ──► README 语义 HTML ├─ GitHubRenderer(user_contentTrue) ── POST /markdown (modegfm) ──► 评论/Issue 语义 HTML └─ GitHubRenderer(user_contentTrue, contextjoeyespo/grip) ──► 带上下文引用解析 HTML │ ▼ patcher.patch(html) ← [任务列表、标题锚点修补](https://link.gitcode.com/i/f78ece846a7813224838e107526a8e7e) │ ▼ render_template 注入 GitHub 样式见 [Grip._render_page](https://link.gitcode.com/i/404ffb1359688c996883d920a5b892a8)两点源码级细节值得注意patch的双重职责patcher.py 除了补齐任务列表复选框还会把 GitHub API 产出的标题锚点图标span{:aria-hidden...}/span修补为正常的 octicon 链接图标以修复 API 与主站间的渲染不一致。本地渲染的降级路径OfflineRenderer 使用 Python-Markdown 并显式加载fenced_code、codehilite、toc、tables、sane_lists与UrlizeExtension六个扩展——其中tables对应 4.6 节表格、UrlizeExtension对应 4.2 节 URL 自动链接、sane_lists处理 3.6 节列表语义。README 将其标注为进行中work in progress因此 gfm-test.md 目前主要服务的是 GitHub API 在线渲染路径。七、如何用这份测试样本验证 grip 渲染7.1 直接预览将本仓库克隆到本地后直接指定该样本文件启动预览$ grip tests/input/gfm-test.md * Running on http://localhost:6419/浏览器打开http://localhost:6419/即可对照本文各节逐一目检渲染结果。若要验证评论/Issue 语义加--user-content并指定上下文$ grip tests/input/gfm-test.md --user-content --contextjoeyespo/grip7.2 运行测试离线单元测试不访问 GitHub API基于 tests/mocks.py 的 mock 响应直接复用 gfm-test.md 做全量渲染比对$ pip install -e .[tests] $ pytest -xm not assumption在线外部假设测试会真实请求 GitHub API断言当前 API 输出与仓库基线一致若 GitHub 端渲染规则变动导致失败则需按 tests/regenerate.py 重新生成基线$ pytest -m assumptiontest_github_readme、test_github_user_content、test_github_user_context三个用例恰好对应本文反复对照的三套基线gfm-test.html、gfm-test-user-content.html、gfm-test-user-context.html。7.3 重新生成基线当 Git 提交更新、需要刷新测试基线时$ python tests/regenerate.py脚本会分别调用regenerate_app()、regenerate_renderer()、regenerate_raw()重写tests/output/下全部三套 HTML依赖本地~/.grip/settings.py中的 GitHub 认证信息见 README 的 Access 一节。八、测试样本中值得注意的边界用例最后汇总 gfm-test.md 里几处坑点它们是排查渲染问题的第一线索意外有序列表行首1986.会被解析为ol start1986必须用1986\.转义才能输出字面文本3.6 节引用式链接的空格陷阱[text] [id]带空格时不会形成完整引用[text]保持字面量3.9 节的双重语义URL 查询参数里的裸与amp;会生成不同 href但显示文本相同3.2 节Unicode 标题H√36中的√会被正常写入锚点user-content-this-is-an-h36说明锚点生成对非 ASCII 是安全的3.4 节任务列表 API 缺失[x]/[ ]字面量必须依赖 grip 的 patcher.py 补丁才能呈现为复选框5.2 节raw 与 user-content 的换行差异同一份输入在两种模式下br插入行为不同排查换行不对的问题时先确认自己用的是哪种模式3.3 节、5.1 节。这份文档的价值在于它既是 grip 的回归测试资产也是一份可独立复用的 GFM 语法验收清单。无论你是想在提交前用 grip 确认 README 效果还是想为自己的渲染器建立语法测试矩阵gfm-test.md 及其三套基线输出raw、user-content、user-context都值得直接取用——输入、预期输出、驱动测试的源码三者齐备闭环完整。赞分享开发工具CLI文档【免费下载链接】gripPreview GitHub README.md files locally before committing them.项目地址https://gitcode.com/gh_mirrors/gr/grip点击查看免费下载相关推荐DeepSeek-OCR离线vs在线推理昇腾NPU环境下的性能测试与选型建议DeepSeek OCR离线vs在线推理昇腾NPU环境下的性能测试与选型建议 在当今AI应用日益普及的时代OCR光学字符识别技术作为信息提取的关键手段TRV校准终极指南Better Thermostat让你的温控精度提升30%TRV校准终极指南Better Thermostat让你的温控精度提升30% Better Thermostat是一款为Home Assistant设计的自定物联网后端gh_mirrors/re/README进阶GitHub Flavored Markdown自定义样式gh_mirrors/re/README进阶GitHub Flavored Markdown自定义样式 痛点直击你还在用单调的README吗 作为开发者文档教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考