（5261期）Markdown – 跨平台 Markdown 语法修复与转换专家

跨平台 Markdown 语法修复与转换专家 Clawic 官方技能，精准诊断并修复 GitHub、MDX、Pandoc 等 10+ 解析器的渲染差异，让同一份文档在任何平台完美呈现。 使用说明 核心用法 本 Skill 是一套面向多平台 Markdown 渲染的完整解决方案，核心能力围绕「诊断-修复-迁移」三大场景展开。 诊断场景：当列表嵌套失效、表格显示为管道符号、代码块吞噬后续内容、锚链接 404、半篇文档意外斜体时，Skill 能快速定位病因——是缺少块级边界、缩进错位、字符未转义、目标不支持扩展语法，还是原始 HTML 被过滤。通过 ## Quick Reference 速查表，用户可按症状直接索引到对应处理文档。 修复场景：提供 9 条核心规则（Rules 1-9），从「命名目标渲染器」到「手术式编辑」，确保修改精准可控。例如 Rule 3 的嵌套列表缩进公式（content column = marker width + 空格数）、Rule 6 的换行符优先级（\ → 双空格 → <br>）、Rule 8 的锚点派生规则（严禁手写锚点，必须按目标 slug 算法生成），均基于不同解析器的实测差异制定。 迁移场景：支持 GitHub ↔ MDX ↔ Pandoc ↔ 文档站点（Docusaurus/MkDocs 等）↔ 协作平台（Slack/Notion/Confluence）之间的双向转换，并处理 HTML↔Markdown、Markdown→PDF/DOCX 等格式转换。转换时自动检查 Support Matrix，确保目标平台支持所用语法。 显著优点 目标感知的精准修复：不同于通用 Markdown 工具，本 Skill 强制要求「先声明目标渲染器」，所有规则均按 target_flavor 条件执行，避免「本地预览正常，线上渲染失败」的陷阱。 平台差异全覆盖：内置 10+ 主流解析器的支持矩阵（CommonMark/GFM/MDX/Pandoc/Python-Markdown/Slack/Discord 等），并针对文档站点生成器（Docusaurus、MkDocs、Hugo 等）和协作平台提供专项处理逻辑。 安全设计严谨：自动识别并脱敏文档中的凭证信息（env:NPM_TOKEN、keychain:docs-deploy 等），严禁将任何 secret 写入 ~/Clawic/data/；对不可信 Markdown 实施「渲染后消毒」策略，MDX 则直接拒绝对不可信来源的渲染。 工程化友好：支持与 markdownlint、Prettier、remark 等工具链集成，提供 CI 配置模板；强调「手术式编辑」原则，避免格式化工具造成的噪音提交。 潜在缺点与局限性 学习曲线陡峭：9 条核心规则 + 多平台支持矩阵 + 配置变量表，对仅需要「简单写个 README」的用户可能信息过载。Skill 明确建议：若目标为 LaTeX 文档、Word 文件、模板化 PDF（报告/发票/合同）或文档架构设计，应使用其他专项 Skill。 非全自动化：强调「用户声明目标」和「手术式编辑」，意味着复杂场景仍需人工判断，无法一键「修复所有 Markdown」。 平台演进依赖：Slack、Notion 等协作平台的 Markdown 支持仍在变化（如 Notion 并非真正 Markdown），Skill 需持续更新适配。 本地化支持有限：虽提及 RTL、CJK 换行等行为配置，但主要优化仍针对英文文档场景。 适合的目标群体 技术写作者：需要确保文档在 GitHub、文档站点、npm/PyPI 页面同时正确渲染 开源维护者：处理来自社区的 PR，保持 README、CHANGELOG 格式规范 DevRel/开发者运营：跨平台发布内容（博客→社交媒体→协作工具） 文档工程师：维护多格式输出（Markdown 源→PDF/DOCX/网站）的文档体系 CI/CD 管理员：配置 Markdown lint、格式检查和链接校验流水线 常规使用风险 性能风险：大文件转换或批量修复时，Pandoc 等外部引擎调用可能耗时；未配置 line_wrap 时，大段落可能造成 Git diff 可读性下降。 依赖项风险：部分功能依赖本地安装的 Pandoc、Node.js 工具链（remark/prettier）或 Python 环境，版本差异可能导致输出不一致。 数据迁移风险：旧数据路径（~/markdown/ 或 ~/clawic/markdown/）需手动迁移至新路径 ~/Clawic/data/markdown/，Skill 会自动提示但需用户确认。 配置漂移风险：target_flavor 等配置若未正确声明，可能按默认 GFM 输出，导致 MDX 或 Pandoc 场景下渲染失败。 扩展语法兼容性：GFM 的 > [!NOTE] 提示框、Mermaid 图表、数学公式等，在目标平台不支持时会静默降级为纯文本，需预先查阅 Support Matrix。 原始说明 Writes, fixes, and converts Markdown that renders the same in every parser — GitHub, MDX, Pandoc, docs sites, Slack, Notion. Use when a list stops nesting, a table renders as literal pipes, a code fence swallows the rest of the file, half a document turns italic, or an anchor link 404s; when frontmatter shows up as text; when footnotes, task lists, callouts, math, or Mermaid render on GitHub but not on the docs site; when MDX rejects `{`, `<`, or an HTML comment; when a README's images break on npm or PyPI; when converting Markdown to PDF, DOCX, or HTML, or HTML back to Markdown; when markdownlint or Prettier fights the file in CI; when pasting into Slack, Discord, Notion, Confluence, or Jira; and when Markdown from an untrusted source has to be rendered safely. Not for LaTeX documents (`latex`), Word files (`word-docx`), templated PDF deliverables such as reports, invoices, and contracts (`pdf-generator`), or documentation strategy and information architecture (`documentation`).