Markdown 是一种用纯文本描述文档结构的写法。行首的 # 表示标题,- 表示列表项,**文字** 表示强调。渲染器读取这些标记后,会生成带有标题、段落和列表的格式化内容,通常是 HTML。
John Gruber 在 Aaron Swartz 的协助下于 2004 年发布了 Markdown。原始项目介绍说明了它希望兼顾可读源码和结构化输出的设计目标。.md 是常见文件扩展名,但只看扩展名不能确认文件的实际内容。
编写一份小文档
将下面的内容粘贴到首页编辑器:
# 团队会议记录
## 决定
保留原始的 **Markdown 源文件**。
- 检查草稿
- 保存本地副本
阅读[项目说明](https://example.com/project)。
> 导出文件与源文件是两份不同的文档。预览中应出现主标题、章节标题、带粗体的段落、列表、链接和引用。先只修改标记里面的文字,观察输出如何变化。保存源文件时应保留这些标记,它们就是文档结构的一部分。
优先掌握的基础语法
| 目标 | 写法 | 检查事项 |
|---|---|---|
| 标题 | ## 决定 |
井号后留一个空格 |
| 新段落 | 两段文字之间留空行 | 仅按一次回车可能仍是同一段 |
| 强调 | *注意*、**必填** |
标记内侧不要紧贴空格 |
| 列表 | 每行以 - 开头 |
缩进决定嵌套层级 |
| 链接 | [项目](https://example.com) |
URL 放在圆括号中 |
| 行内代码 | `notes.md` |
反引号让语法按原样显示 |
| 引用 | > 一段引用 |
后续引用段落也保留前缀 |
多行代码可用独立成行的三个反引号包围。在开始的反引号后写语言名称,目标平台支持时就能显示语法高亮。更多可复制示例见 Markdown 速查表(英文)。
为什么不同平台的预览不完全一样?
Markdown 有不同实现和扩展。CommonMark 规范定义了基础行为,GitHub Flavored Markdown增加了表格、任务列表、删除线等语法。公式、Mermaid 图表、脚注和平台提示框还需要额外支持。
支持 GFM 并不意味着会重现 GitHub 的全部样式和平台功能。MD File Viewer 会移除用户输入的原始 HTML 标签,因此 HTML 下划线在这里可能消失,即使另一个平台允许它。可参阅下划线兼容性指南,并在最终发布位置再次检查。
保存源码,再选择导出格式
需要继续编辑时,请保留本地 .md 文件。只保存截图或 PDF 无法保留原始 Markdown 结构。已有文件可通过 MD 文件打开器读取。
网页或 CMS 内容可用 HTML 导出,需要别人修改时可用 Word 导出,需要固定页面外观时可用 PDF 导出。请打开导出文件检查:当前直接下载的 PDF 是图像形式,文字不能直接搜索或选中;Word 保留许多可编辑文本结构,但 Mermaid 仍显示为代码,不支持的公式可能被省略。
常见问题排查
标题没有生效。 检查是否写成 # 标题,以及这行是否位于未关闭的代码块内。
两行变成了一段。 新段落之间留空行。需要在同一段内换行时,在行末使用两个空格或反斜杠。
本地图片不见了。 导入 .md 不会同时导入整个文件夹。相对路径图片需要在最终发布位置提供对应的文件和目录。
浏览器处理是否代表没有网络请求? 文档解析在浏览器内完成,但远程图片仍可能访问图片服务器。首页编辑器还会在当前浏览器的本地存储中保留草稿。请阅读隐私政策,有保密要求的文档应遵循所在组织的处理规则。
练习时一次修改一处,确认预览后再保存源文件。这样更容易定位是哪一个标记导致了排版问题。
在浏览器中试试
打开首页编辑器,无需安装应用即可查看、编辑和下载 Markdown。