Skip to content

fix(docs): 修复 Extra05 SKILL.md 示例的代码块嵌套渲染错误 - #845

Open
1-fdf wants to merge 1 commit into
datawhalechina:mainfrom
1-fdf:fix/extra05-codeblocks
Open

fix(docs): 修复 Extra05 SKILL.md 示例的代码块嵌套渲染错误#845
1-fdf wants to merge 1 commit into
datawhalechina:mainfrom
1-fdf:fix/extra05-codeblocks

Conversation

@1-fdf

@1-fdf 1-fdf commented Aug 25, 2026

Copy link
Copy Markdown

问题描述

《Agent Skills 解读》(Extra-Chapter/Extra05-AgentSkills解读.md)"实践案例:MySQL 员工分析 Skill 详解"一节,用 markdown 围栏展示了一份完整的 SKILL.md 示例,但示例内部又包含 python 代码块和多段 SQL,产生围栏嵌套冲突。

按 CommonMark 规则,内层 ``` 会直接关闭外层代码块,导致渲染错乱:

  1. 从"第三步:执行查询"的 ```python 处外层块被提前关闭,示例后半部分("第四步:解读结果"、"常见查询模式")泄漏到文档正文层级渲染:标题变成真实标题、五段 SQL 以正文段落显示
  2. 五个查询模式的 SQL 均无代码块包裹
  3. 示例结尾("故障排查"之后)残留一个孤立 ,反向开启一个新代码块,把"这个 SKILL.md 文件展示了一个完整技能的结构"、"技能的使用效果"、输出表格、"关键洞察"、"Skills 的分享与复用"等内容全部吞进代码块,直到后文一个 bash 才意外闭合

修改内容

  • 外层示例围栏 ```markdown → ````markdown(四反引号嵌套写法,CommonMark 标准方案)
  • 补上"第三步:执行查询"中 ```python 代码块缺失的闭合围栏
  • 为 5 个查询模式(模式 1~5)的 SQL 补上 ```sql 围栏
  • 示例结尾的孤立 ``` 改为 ````,正确闭合外层示例块

验证

  • 对修改后全文按 CommonMark 围栏规则(开启长度为 N 的围栏,需 ≥N 个反引号才能闭合)做了配对检查:16 个代码块全部正确闭合,该示例整体(约 360-585 行)为单一完整代码块,内部 python / sql 均作为字面内容
  • 仅改动围栏相关行,未改动任何文字内容

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