Markdown 将源文本与呈现分离
Markdown 文件是普通文本，通常以 .md 扩展名保存。即使没有专门的应用程序，源文本也易于理解，而 GitHub、文档工具、静态站点生成器和编辑器都可以用排版和导航将其渲染出来。
这种分离是核心思想：作者用少量词汇描述含义，由目标环境决定最终呈现效果。同一个 README 既可以在终端、代码评审中轻松阅读，也能呈现在精美的文档网站上。
example.mdMarkdown
# Deploying the API Run the **smoke tests** before release. - Verify health checks - Review error rates - Tag the build
为什么 Markdown 适合技术写作
Markdown 将写作与评审之间的距离缩至最小。源文本几乎没有视觉噪音，变更会产生有用的逐行差异，文件可以与它所说明的代码或配置放在一起。
- 可移植：纯文本不依赖于任何特定厂商或编辑器。
- 可差异比对：变更很容易在版本控制中检查。
- 可组合：文档工具可以将其转换为 HTML、PDF 或帮助内容。
- 易读：即使在渲染之前，源文本也很有用。
- 可自动化：脚本可以检查链接、标题、示例和风格规范。
Markdown 有核心语法和多种变体
共同的核心语法涵盖段落、标题、强调、链接、图片、引用、列表和代码。平台通常会添加扩展。例如，GitHub Flavored Markdown 在开发者工作流中普及了表格、任务列表和删除线。
扩展很有用，但可移植性仍然重要。一个简单的标题几乎处处可用；而平台专属的图表块则未必。当文档需要在不同工具之间迁移时，请在目标环境中测试语法，并将重要含义保留在普通文本中。
Markdown 的使用场景
只要内容需要与软件保持紧密联系或走基于文本的工作流，Markdown 就十分常见。在工程之外的场景中，当持久、低摩擦的源文本比精确的页面布局更有价值时，它也同样有用。
- README 文件、贡献指南、变更日志和发布说明
- API 参考、教程、运行手册和架构决策记录
- Issue 描述、Pull Request、评论和团队知识库
- 静态网站、博客、产品文档和内部手册
- 发布前需要清理的笔记或转换后的文档
Markdown 不擅长做什么
Markdown 不是页面排版格式。精确字体、分栏、浮动对象、打印分页和复杂的交互组件属于其他系统的范畴。转换后的 PDF 或演示文稿更易于保留有用的文本，而非其视觉布局。
同时，仅仅因为是纯文本，它也并不自动安全。渲染器必须将链接和可选的原始 HTML 视为不可信内容。好的编辑器会对预览输出进行净化，发布管线也会应用自己的安全策略。