v0.10.1 - GitHub 标题 ID、代码块解析与链接规范化修复

GitHub 标题 ID、代码块解析与链接规范化修复

v0.10.1 新增了与 GitHub 兼容的扁平标题 ID 支持,并修复了 MDX 编译中的代码块保留、包含点号及查询参数的文件名内部链接规范化以及 MkDocs 迁移工具中的侧边栏解析改进。

Added

  • 与 GitHub 兼容的扁平标题 ID (@docmd/parser): 增加了 "markdown": { "headingIds": "github" } 选项(或页面 frontmatter headingIds: github),以遵循 GitHub 的 slug 规范生成扁平标题 ID(小写、去除标点符号但不折叠连续连字符、空格转连字符、同页面重复标题追加 -1、-2 后缀)。默认情况下,docmd 继续保留原有的分层上下文标题 ID("nested")。由 @thinkbig1979 在 #286 中提议。

Fixed

  • 代码块表达式解析修复 (@docmd/plugin-mdx, lite-mdx): 升级 lite-mdx 至 0.1.2,提供完全符合 CommonMark 标准的代码围栏扫描。包含引号、标题或语言属性的代码块(例如 ```json "docmd.config.json")现在受到严格保护,免于 JSX/MDX 表达式编译。此外,@docmd/plugin-mdx 现在仅在存在 JSX 语法或导入/导出语句时才对 .md 文件触发 MDX 处理。
  • 包含点号与查询字符串的内部链接 (@docmd/parser): 修复了文件名包含点号的 Markdown 页面链接(如 release-1.0.md、docmd.config.md)被误分类为原始静态资源、导致跳过末尾斜杠和子页面 ../ 深度调整的问题。查询字符串(如 other.md?tab=npm、index.md?tab=npm)现在会在去除扩展名之前与哈希片段一起被提取,并在相对深度调整时予以完整保留。解决 #284。
  • MkDocs 导航迁移 (@docmd/core): docmd migrate --mkdocs 现在会在遇到下一个顶级 YAML 键时终止导航解析(防止将 plugins: 和 markdown_extensions: 误加入侧边栏),去除标题/路径上的引号,并将 index.md 正确映射到根 / 或子目录 <dir>/ 路由。由 @jayhemnani9910 在 #285 中贡献。
  • 动态版本测试断言: 更新了 tests/cli-contracts/variables-engine.test.js 中的测试断言,动态校验 registry.get('docmd.version')。

Documentation & Diagnostics

  • 标题 ID 与链接规范化指南: 补充了针对 markdown.headingIds 的完整配置与 frontmatter 参考文档,并在四种语言中均补充了对包含点号的文件名及查询参数链接的保留说明。
  • Iconify 插件文档: 在所有四种语言(en、de、es、zh)的 plugins/iconify.md 中添加了专属文档和实时交互式容器示例(Callout、Button、Card、Tab、Tag)。
  • 嵌套代码块格式化: 修复了 Tabs 组件示例中的嵌套代码围栏转义,使用 4 个反引号块和外层 ::: tabs 容器语法。

文档: https://docs.docmd.io/
云平台: https://cloud.docmd.io/
开发与写作技能: https://github.com/docmd-io/docmd-skills

New Contributors

完整变更日志: https://github.com/docmd-io/docmd/compare/0.10.0...0.10.1