Skip to main content

Markdown 语法

Markdown 是一种轻量级标记语言,用于格式化文本。它简单易学,广泛应用于文档编写、博客、论坛等。

基础语法

标题

强调

效果:斜体、粗体、粗斜体、删除线

列表

无序列表

有序列表

链接

图片

引用

代码

行内代码

代码块

分割线


表格

任务列表

  • 已完成任务
  • 未完成任务

脚注

Github Flavored Markdown (GFM)

GitHub 对 Markdown 进行了扩展,增加了一些特性。

语法高亮

表情符号

:smile: :heart: :+1: :rocket: 表情符号列表

@提及和#引用

自动链接

GitHub 会自动将 URL 转为链接:

Diff 代码块

折叠内容

Alert 警告框(GitHub新特性)

数学公式

使用 LaTeX 语法:

Mermaid 图表

高级技巧

HTML 嵌入

Markdown 支持直接使用 HTML:

字符转义

使用反斜杠转义特殊字符:

锚点链接

徽章 Badge

目录生成

常用工具

  • 编辑器:Typora, VS Code, Obsidian
  • 在线编辑:StackEdit, Dillinger
  • 格式化:Prettier, markdownlint
  • 转换:Pandoc (Markdown to PDF/Word/HTML)

最佳实践

  1. 保持简洁:Markdown 的优势在于简单
  2. 使用标题:合理的层级结构
  3. 代码高亮:指定语言提升可读性
  4. 图片优化:控制图片大小
  5. 预览检查:编写后及时预览效果
  6. 版本控制:Markdown 适合 Git 管理
  7. 链接检查:确保链接有效
  8. 考虑用 HTML 做 Agent 的丰富输出:当 AI Agent 生成包含表格、图表和交互元素的长文档时,HTML 可能比 Markdown 更有表达力(见下方)。

HTML vs Markdown:Agent 时代的输出格式选择

在 AI Agent 时代,输出格式的选择比以前更重要。当 Agent 来写和改文档时,Markdown 的核心优势——“方便手动编辑”——就不存在了。应该换 HTML 吗?

Markdown 仍然适用的场景

  • 短文档(约100行以内)— Markdown 仍然是最简单的格式
  • 配置文件、README、变更日志 — Git友好,diff 清晰
  • 知识库页面(如本站)— Mintlify/Jekyll 渲染 Markdown 很漂亮
  • 团队 Wiki — 版本控制和协作编辑很重要

HTML 有优势的场景

HTML 的五个典型用例

  1. 规划与探索 — 生成”HTML 文件网络”:6个方向并排对比,再做 mockup,最后形成实施计划
  2. 代码审查 — 渲染 diff、内联注释和流程图在一个页面
  3. 设计原型 — HTML 作为设计中间语言,再翻译到 React/Swift
  4. 报告与学习 — 跨源综合,输出交互式讲解或幻灯片
  5. 一次性编辑器 — 为某个具体任务(重排30个ticket、调feature flag、调system prompt)造一个抛弃式 UI,关键是末尾要有”导出为 JSON/prompt”按钮

权衡

  • 生成耗时 — HTML 需要 2–4× Markdown 的时间
  • Token 成本 — 更高,但在 1M+ 上下文窗口下不再敏感
  • 版本控制 — HTML diff 很吵,难以 review — 这是 Markdown 最大的残留优势
  • 风格一致性 — 需要一个”设计系统 HTML 文件”作为参考来约束风格
对于知识库和版本控制文档,Markdown 仍然是默认选择。只在输出是一次性报告、审查产物或交互原型时用 HTML——这些东西不需要 Git diff review。

参考资源

最后修改于 2026年5月9日