Markdown 写作与排版教程写作目的有些技术文章内容正确但排版不够清晰读者阅读和复制示例时容易遇到困难。本文介绍常见 Markdown 语法并说明代码块、链接、图片和 Mermaid 示例的兼容性问题。本文以 CommonMark/GFM 为基础。表格、删除线和任务列表属于常见扩展Mermaid、图片尺寸、图片对齐和原始 HTML 是否可用取决于发布平台。发布前应在目标平台实际预览。目录1. Markdown 是什么2. 基础语法3. 代码和图片4. 链接、锚点和 Mermaid5. 综合示例6. 排版建议7. 总结1. Markdown 是什么Markdown 是一种轻量级标记语言。作者使用易读、易写的纯文本标记编写文档渲染器再将其转换为 HTML。Markdown 适合编写技术文档、博客文章、项目说明和 README 文件。Markdown 没有一个完全统一的扩展集合。常见环境包括CommonMark更接近基础规范GFMGitHub Flavored Markdown支持表格、删除线等扩展CSDN Markdown包含平台自定义的图片尺寸和对齐写法支持 Mermaid 的编辑器或网站可以渲染 Mermaid 图表。不要把某个平台的扩展写成所有 Markdown 渲染器都支持的通用语法。2. 基础语法2.1 标题ATX 风格标题使用 1 至 6 个井号并在井号后添加空格# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题通常一篇文章只使用一个一级标题章节使用二级标题小节使用三级标题。标题的字体大小、粗细和颜色由渲染器主题决定。2.2 段落和换行连续文本行通常属于同一个段落段落之间使用空行分隔这是第一段。 这一行仍然属于第一段。 这是第二段。普通换行是否在页面上显示为换行取决于渲染器。需要强制换行时可以使用反斜杠这一行末尾使用反斜杠\ 下一行会显示为换行。也可以使用 HTML 的br但这属于平台相关写法。缩进并不总是错误。通常 4 个空格或一个 Tab 可能表示缩进代码块列表内部的缩进规则还与列表标记的位置有关。因此不要笼统地说“每行开头不能有缩进”。2.3 强调*斜体文本* _斜体文本_ **粗体文本** __粗体文本__删除线通常属于 GFM 扩展~~删除线文本~~2.4 列表无序列表可以使用短横线、星号或加号建议全文统一使用短横线- 第一项 - 第二项 - 第三项有序列表使用数字加英文句点建议连续编号1. 第一项 2. 第二项 3. 第三项许多渲染器会自动显示连续编号但第一个编号可能影响列表的起始数字不能假设所有平台都会忽略源文件编号。嵌套列表需要增加缩进- 一级项目 - 二级项目 - 另一个二级项目 - 另一个一级项目2.5 链接行内链接的格式是[链接文本](https://example.com)参考链接可以集中定义这是一篇关于 [Markdown][markdown-doc] 的文章。 [markdown-doc]: https://commonmark.org/参考链接定义不一定必须放在文档最后但集中放置在文档末尾通常更容易维护。2.6 图片标准 Markdown 图片语法是替代文本会在图片无法显示时提供提示也会被屏幕阅读器读取因此不建议使用没有意义的Alt作为内容。没有替代文本时可以使用空文本example.com/image.png只是占位地址不保证存在。发布文章时应替换成真实地址或仓库中的相对路径。3. 代码和图片3.1 行内代码和代码块行内代码使用一对反引号包围运行 python main.py 启动程序。代码块使用三个反引号。指定语言后支持语法高亮的渲染器可以使用对应的规则defhello_world():print(Hello, World!)hello_world()常见语言标识包括python、cpp、javascript、html、css和bash。如果要展示本身含有三个反引号的 Markdown 源码外层必须使用四个或更多反引号python print(Hello, World!) 外层使用四个反引号后内部的三个反引号不会提前关闭外层代码块。也可以用波浪线代码块作为外层标记。3.2 表格表格通常属于 GFM 扩展| 姓名 | 年龄 | 城市 | | --- | ---: | :---: | | Alice | 18 | 北京 | | Bob | 20 | 上海 |3.3 图片尺寸和对齐标准 Markdown 没有统一的图片宽度、高度和对齐语法。若平台允许 HTML可以使用imgsrchttps://example.com/image.pngalt示例图片width60height60CSDN 等平台可能支持自定义写法例如这段写法不应标记为通用 Markdown换到其他渲染器后尺寸和对齐可能失效。4. 链接、锚点和 Mermaid4.1 文档内锚点自动生成的标题锚点没有统一规则。不同平台可能会转换大小写、空格、标点和中文字符因此长文档可以使用显式锚点a idsection-one/a ## 第一部分 返回 [第一部分](#section-one)。这依赖平台允许原始 HTML。如果平台会过滤 HTML应改用该平台生成的标题链接。不要使用无法确认目标的链接[回到顶部](#1)如果标题是# 1. Markdown 是什么其自动锚点通常不会简单地等于#1。本文在开头设置了idtop因此统一使用[回到顶部](#top)4.2 MermaidMermaid 是独立的文本图表工具。只有支持 Mermaid 的渲染器才会将下面的代码块绘制成图表。4.2.1 流程图是否开始是否完成提交结果继续处理常见节点写法包括A[文本]矩形A(文本)圆角矩形A((文本))圆形A{文本}菱形。--表示带箭头的连接---表示没有箭头的连接。4.2.2 序列图系统用户系统用户登录请求登录成功在participant U as 用户中U是内部标识符用户是显示名称。4.2.3 甘特图2025-05-012025-05-022025-05-032025-05-042025-05-052025-05-062025-05-072025-05-082025-05-092025-05-102025-05-112025-05-122025-05-132025-05-142025-05-15设计开发测试发布第一部分第二部分项目进度dateFormat用于指定日期格式。done、active等状态是否支持取决于 Mermaid 版本。5. 综合示例下面是一个完整的 Markdown 源码示例。因为示例内部还包含代码块所以使用四个反引号作为外层代码块a idexample-top/a # Markdown 示例文档 ## 目录 - [简介](#example-intro) - [代码示例](#example-code) - [流程图](#example-flowchart) - [总结](#example-summary) a idexample-intro/a ## 简介 本文展示如何组织一篇包含标题、列表、代码和图表的技术文章。 ### 项目功能 - 读取数据 - 清洗数据 - 生成处理结果。 a idexample-code/a ## 代码示例 下面的代码需要存在 data.csv且文件中包含 date 和 age 列。 python import pandas as pd data pd.read_csv(data.csv) data data.dropna().drop_duplicates() data[date] pd.to_datetime(data[date]) data[age] data[age].astype(int) data.to_csv(cleaned_data.csv, indexFalse) a idexample-flowchart/a ## 流程图 mermaid flowchart TD A[读取数据] -- B[清洗数据] B -- C[生成结果] a idexample-summary/a ## 总结 清晰的标题层级、稳定的代码块和明确的链接可以提高文章的可读性。 [回到顶部](#top)这里使用四反引号包住整个示例因此内部的 Python 和 Mermaid 代码块不会破坏外层结构。6. 排版建议6.1 保持标题层级清晰建议使用一个一级标题章节使用二级标题小节使用三级标题。不要为了显示更大的字体跳过层级。6.2 让示例可复制代码示例应使用正确的语言标识和完整的围栏。需要展示 Markdown 源码时使用四反引号或波浪线作为外层围栏。6.3 说明平台差异文章使用 GFM、Mermaid、CSDN 图片扩展或原始 HTML 时应明确写出兼容范围不要把平台扩展描述为 Markdown 的通用语法。6.4 提供有意义的替代文本图片替代文本应描述图片内容或用途例如项目流程图不要只写Alt或图片。6.5 发布前预览发布前至少检查标题层级是否正确代码围栏是否成对链接和图片是否能够访问Mermaid 是否能正常渲染目标平台是否支持所使用的扩展移动端换行和表格是否可读。7. 总结Markdown 的基础语法简单但不同渲染器支持的扩展并不完全相同。写作时应先确定目标平台再统一标题、段落、列表、代码、图片和链接的写法。对于包含代码块的 Markdown 源码使用四反引号作为外层围栏对于 Mermaid、图片尺寸和对齐语法应标明它们的兼容范围。这样既能保持文章结构清晰也能减少读者复制示例时遇到的解析错误。回到顶部
