用途
这是一份 Markdown 撰写参考资料，用于编写文档、README 和技术写作。资料覆盖核心语法、GFM 扩展、README 模式、技术文档、MDX 和 linting。
核心语法
标题使用 ATX 风格（#），不要在 # 后省略空格，不要跳级，每个文件只用一个 H1。强调与行内元素支持 斜体、加粗、粗斜体、删除线、行内代码、<kbd>Ctrl+C</kbd>、<sup>super</sup>、<sub>sub</sub>，优先使用 * 而非 _。
链接与图片支持行内链接、带标题链接、相对路径、锚点链接和图片语法，长文档中可使用引用式链接。
列表支持无序（用 -，嵌套缩进 2 空格）和有序列表，以及 GFM 任务列表。代码块需始终指定语言，如 javascript、typescript、python、bash、json、yaml、sql、html、css、diff。还支持引用块和水平分割线。
GFM 扩展
表格支持对齐（左、居中、右）。支持 GitHub Alerts（[!NOTE]、[!TIP]、[!IMPORTANT]、[!WARNING]、[!CAUTION]）。支持脚注、自动链接、@提及、#123 issue 引用和 org/repo#456 跨仓库引用。
高级模式
支持可折叠区块（<details>/<summary>）、LaTeX 数学公式、Mermaid 图表（流程图与序列图）、目录。锚点规则为小写、空格转 -、去除标点，可用 scripts/markdown-linter.sh 的 generate_toc 函数、VS Code 的 Markdown All in One 或 markdown-toc npm 包自动生成。
README 撰写
支持 shields.io 徽章（构建、版本、许可证、覆盖率、自定义），参数包括 ?style=flat-square、?logo=typescript、?label=custom、?color=ff6600。标准 README 章节顺序为：项目名称 + 徽章、Features、Quick Start、Installation、Usage、Configuration、Contributing、License。项目结构树可用 tree -I node_modules 生成并加注释。
技术文档
推荐层级：Overview、Prerequisites、Installation、Quick Start、Detailed Guide、API Reference、Troubleshooting、Changelog。API 端点可结合字段表格与响应 JSON 代码块呈现。
MDX
MDX 将 markdown 与 JSX 结合，用于交互式文档（Docusaurus、Nextra、Astro）。MDX v2+ 使用 ESM imports。
Linting
可使用 markdownlint（npm install -g markdownlint-cli，配合 .markdownlint.json 配置）和 remark-lint。关键规则包括 MD001 标题递增、MD009 无尾随空格、MD013 行长、MD024 无重复同级标题、MD033 无行内 HTML、MD041 首行为 H1。CI 中可使用 DavidAnson/markdownlint-cli2-action@v19。还可用 scripts/markdown-stats.py 估算阅读时间与词数。
转换
可使用 pandoc 转换为 HTML（含 --toc 选项）、PDF（需 LaTeX），或使用 marked 进行 GFM 兼容转换。
常见错误
列表前缺少空行、标题后缺少空行、URL 含空格需编码、代码围栏缺少语言、混用 * 和 -、嵌套列表缩进错误、--- 上方缺少空行、裸 URL、字符需转义（\ ` * _ {} [] () # + - . ! |）。
编辑器设置
VS Code 可使用 Markdown All in One、markdownlint、Markdown Preview Mermaid Support、Paste Image。Prettier 可在 *.md 的 override 中加入 "proseWrap": "always" 和 "printWidth": 80。