Markdown 新手写作教程:从第一行文字到完整博客文章
这份教程面向第一次接触 Markdown 的读者。你不需要先学习 HTML,也不需要有编程基础。学完基础部分,就可以用 Markdown 写学习笔记、技术博客、操作说明和项目文档。
教程采用“用途 → 原始写法 → 显示效果或解释 → 常见错误”的方式。示例中的文章、数据和练习均为教学示例。
阅读时请分清两种内容:
- 标注“原始写法”的代码框:展示你应当输入到
.md文件中的字符。 - 代码框外的正常文字、列表和表格:展示排版效果,或者解释这些字符的作用。
不要把整份文章套在一个代码框里。 只有想把某一段内容当作代码展示时,才给那一段添加代码围栏。你下载的这份 .md 文件可以直接用文本编辑器打开,也可以在支持 Markdown 的软件中预览。
阅读路线
| 你的目标 | 建议阅读内容 |
|---|---|
| 尽快开始写文章 | 第 1—7 节、第 11—14 节、第 23 节 |
| 写结构完整的技术博客 | 第 1—17 节、第 22—26 节 |
| 写带数学公式的学习笔记 | 基础部分,再看第 18—20 节 |
| 出现显示问题时查原因 | 第 27 节 |
| 动手练习并自测 | 第 29 节 |
| 忘记某个符号时快速查阅 | 第 30 节 |
教程较长,不必一次记住。先打开一个练习文件,每学一个语法就输入一次,再看预览。
1. Markdown 到底是什么
1.1 用少量符号表达文章结构
Markdown 是一种轻量级标记语言。你使用普通文字和少量符号,告诉软件“这里是标题”“这里是列表”“这里需要强调”。
例如,你输入:
# 我的学习笔记
今天学习了 **Markdown**,并练习了下面三种写法:
- 标题
- 列表
- 代码块
支持 Markdown 的软件会把第一行显示为标题,把 Markdown 显示为粗体,把最后三行显示为列表。
这里的 #、** 和 - 都是标记。它们让文字具有结构,通常不会原样出现在排版后的正文中。
1.2 文件、编辑器、预览器分别是什么
| 名称 | 含义 | 例子 |
|---|---|---|
| Markdown 文件 | 保存文章源文字的文件 | study-note.md |
| 编辑器 | 用来输入和修改文字的软件 | Vim、VS Code、记事本 |
| Markdown 渲染器 | 把语法转换为排版结构的程序 | 编辑器或博客系统内部的转换程序 |
| 预览界面 | 展示转换后的文章 | VS Code 的 Markdown 预览 |
| 网站主题 | 决定网页字体、颜色、宽度等外观 | 博客所使用的主题和样式 |
你在 Vim 中看到 # 标题,说明你在编辑源文字;在预览中看到放大的标题,说明渲染器已经处理了它。
源文字和预览是同一篇文章的两种呈现方式。
1.3 .md 和 .txt 有什么区别
它们都可以保存纯文本。.md 扩展名通常用来告诉软件:“请按 Markdown 的规则理解这个文件。”
下面两个文件都可能包含相同的字符:
study-note.txt
study-note.md
但是编辑器通常会更容易识别 .md 文件,并提供语法高亮和预览入口。
把文件改成 .md 不会自动替你整理标题或补充语法;文件里面仍然需要写正确的内容。
1.4 哪些效果由 Markdown 控制
Markdown 主要表达文章结构,例如:
- 哪一行是标题。
- 哪几个词需要强调。
- 哪些内容属于同一个列表。
- 哪段文字是代码。
- 哪个文字链接到哪个地址。
标题具体多大、字体是什么、引用框是什么颜色,通常由预览器或网站主题决定。
因此,同一份文件在不同软件里,外观可以不同,但标题、段落、列表等基本结构应当大致一致。
1.5 基础语法与扩展语法
不同平台支持的 Markdown 功能并不完全一样。教程会采用以下分类:
| 类型 | 本教程中的例子 | 使用时的判断方式 |
|---|---|---|
| 基础语法 | 标题、段落、强调、列表、链接、图片、引用、代码 | 优先掌握,兼容性通常较好 |
| 常见扩展 | 表格、任务列表、删除线 | 很多平台支持,但不是所有解析器都默认支持 |
| 平台或插件功能 | 公式、脚注、流程图、自动目录、提示框 | 先确认目标平台是否支持 |
| 博客系统功能 | 标题元数据、日期、草稿、分类、标签 | 按博客系统和主题的规则填写 |
CommonMark 是一套明确规定 Markdown 解析方式的规范;GFM 是 GitHub Flavored Markdown 的简称,在 CommonMark 基础上定义了若干扩展。一个网站还可能在 GFM 之外增加公式、脚注等功能。
参考:CommonMark 规范;GFM 规范。
2. 先创建一个真正的 Markdown 文件
2.1 文件名怎么起
可以使用:
markdown-practice.md
java-array-notes.md
linux-basic-commands.md
我的第一篇笔记.md
中文文件名可以使用。为了在命令行、网页地址和不同系统之间传递更省事,也可以采用“小写英文单词 + 连字符”的习惯,例如 java-array-notes.md。
注意最后的扩展名:
正确:markdown-practice.md
容易误保存:markdown-practice.md.txt
有些系统会隐藏已知扩展名。如果软件没有识别 Markdown,检查文件实际名称是否多了 .txt。
2.2 用 VS Code 创建
- 新建文本文件。
- 输入几行内容。
- 保存,文件名填写
markdown-practice.md。 - 确认编辑器把文件识别为 Markdown。
- 打开 Markdown 预览,对照源文字查看效果。
具体预览快捷键在第 23 节。
2.3 用 Vim 创建
下面这一行应当在终端中执行:
vim markdown-practice.md
进入 Vim 后:
- 按小写
i,进入插入模式。 - 输入或粘贴文章。
- 按
Esc,回到普通模式。 - 输入
:w并按回车,保存。 - 输入
:q并按回车,退出。
也可以在普通模式输入 :wq 并按回车,一次完成保存和退出。
终端命令、Vim 命令、Markdown 正文是三种不同的内容。
| 内容 | 在哪里输入 | 用途 |
|---|---|---|
vim markdown-practice.md |
终端 | 打开文件 |
:w |
Vim 普通模式下的命令行 | 保存文件 |
# 我的笔记 |
文件正文中 | 写一个 Markdown 标题 |
不要把 :wq 当成文章内容,也不要把 # 我的笔记 当成终端命令执行。
2.4 先完成一个最小练习
把下面的内容复制到练习文件中:
# 我的第一篇 Markdown 笔记
今天我开始学习 Markdown。
## 学习目标
- 写出标题。
- 写出列表。
- 给重点文字加粗。
**今天先把基础语法练熟。**
先保存、打开预览,确认能看到标题、列表和粗体,再继续学习。
3. 输入符号前,先认识半角字符
Markdown 的语法符号通常使用英文半角字符。中文正文照常输入;写语法标记时,要留意输入法产生的符号。
| 用途 | 应使用的字符 | 不要混淆成 |
|---|---|---|
| 标题 | # |
# |
| 强调 | * |
* |
| 无序列表 | - |
- 或中文破折号 |
| 链接文字 | [ 和 ] |
【 和 】 |
| 链接地址 | ( 和 ) |
( 和 ) |
| 引用 | > |
> |
| 图片 | ! |
! |
| 转义 | \ |
/ |
| 代码 | 反引号 ` |
单引号 ' |
3.1 反引号和单引号尤其容易混淆
下面这两种写法不同:
`这是用反引号包围的内容`
'这是用单引号包围的内容'
第一种通常会变成行内代码,第二种仍然是普通文字。
在常见美式键盘布局上,反引号和 ~ 通常位于同一个键,位置多在数字 1 的左侧;其他布局可能不同。判断时认字符本身,不要只记位置。
3.2 空格也是语法的一部分
先记住以下写法:
# 标题
- 列表项目
1. 操作步骤
> 引用内容
标题标记、列表标记后面要留空格;引用标记后面也建议留一个空格,使源文字清楚易读。
不要写成:
#标题
-列表项目
1.操作步骤
这些写法在常见解析规则下不会按预期成为标题或列表。
4. 标题:先搭好文章骨架
4.1 六级标题
原始写法:
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
# 的数量表示标题级别。一个 # 表示一级标题,六个 # 表示六级标题。
最多六级。 七个 # 不会按这种写法得到七级标题。
4.2 标题级别表示结构
写一篇学习笔记时,可以这样组织:
# Java 数组学习笔记
## 1. 数组是什么
### 1.1 数组中的元素
### 1.2 数组的下标
## 2. 如何创建数组
## 3. 常见错误
其中:
#:整篇文章的标题。##:文章中的主要部分。###:某个主要部分下面的细分内容。
一般先使用前三个级别。不要为了让某句话“看起来小一点”,随意从一级标题跳到五级标题。
4.3 标题中的编号需要你填写
例如:
## 1. 数组是什么
## 2. 如何创建数组
这里的 1. 和 2. 是标题文字的一部分,基础 Markdown 不会替你自动给章节编号。
4.4 标题上下空一行
建议采用:
上一段正文。
## 新的小节
这一小节的正文。
有些解析器允许标题紧贴正文,但空行可以减少歧义,也方便你在源文件中寻找章节。
4.5 不要用粗体代替标题
**数组的定义**
这是一段加粗文字,不等于:
## 数组的定义
真正的标题能被很多软件用于生成文章大纲和目录。粗体主要用于段落内部的强调。
4.6 一篇文章需要几个一级标题
作为写作习惯,独立文档通常保留一个一级标题。
如果博客主题已经根据文章元数据自动显示了主标题,正文可能应从 ## 开始,避免主标题重复。是否省略正文中的一级标题,要看实际页面,不是所有博客都一样。
5. 段落、换行和空行:新手最容易混淆的地方
5.1 普通文字直接写
今天我学习了 Markdown 的标题语法。
不需要给每一行添加特殊标记。
5.2 两个段落之间空一行
原始写法:
这是第一段,介绍今天的学习内容。
这是第二段,记录学习中遇到的问题。
显示效果:
这是第一段,介绍今天的学习内容。
这是第二段,记录学习中遇到的问题。
在上一段结尾按一次回车,只是进入下一行;再按一次回车,让中间出现一条空行,才构成常见的分段写法。
5.3 只按一次回车,不一定在预览中换行
原始写法:
这是源文件中的第一行。
这是源文件中的第二行。
按 CommonMark 一类规则,这通常还是同一个段落,普通换行叫作“软换行”。实际页面是否保留换行,取决于渲染器的设置。
因此,不要因为编辑器里分成两行,就认定网页也一定显示成两行。
5.4 想在同一段内明确换行,可以怎么写
方法一:在行尾添加两个普通空格,再回车。
下面第一行句号后面有两个空格:
第一行。
第二行。
这两个空格不可见,复制时也可能被编辑器清除。为了说明位置,可以把它理解成下面的示意:
第一行。[空格][空格]
第二行。
其中 [空格] 只是说明,不能原样写进文章。
方法二:在支持 CommonMark 写法的平台上,在行尾添加反斜杠。
第一行。\
第二行。
这里使用的是反斜杠 \,不是斜杠 /。反斜杠应当紧接行尾换行。
方法三:平台允许内嵌 HTML 时,使用 <br>。
第一行。<br>
第二行。
新手日常写文章,优先采用“一个意思写成一个段落,段落之间空一行”。只在地址、诗行等确实需要时使用段内强制换行。
5.5 三种情况对照
| 源文件里的操作 | 主要含义 | 常见预览结果 |
|---|---|---|
| 普通回车一次 | 同一段中的软换行 | 可能连成一段显示 |
| 中间留一条空行 | 新段落 | 分成两个段落 |
| 行尾两个空格或受支持的反斜杠,再回车 | 段内硬换行 | 同一段中明确换到下一行 |
5.6 多空几行,不一定产生更大的间距
连续空五行,通常不会在网页中得到“五行高度的空白”。段落间距主要由页面样式决定。
同样,不要用很多空格来对齐正文。连续空格在普通网页文字中可能折叠。如果需要排列项目,使用列表或表格。
5.7 不建议给每段开头输入四个空格
Markdown 中,段落位置上的四空格缩进可能被解释为代码块。
如果你希望文章有中文首行缩进,应优先让网站主题或排版样式负责,而不是在每段前手工敲四个空格。
6. 强调文字:粗体、斜体和删除线
6.1 粗体
原始写法:
学习 Markdown 时,**空行和缩进**很重要。
显示效果:
学习 Markdown 时,空行和缩进很重要。
左右各两个星号,共四个。不要写成 ** 重点内容 **,标记内部两端留空格可能导致强调失效。
6.2 斜体
原始写法:
这里是 *需要轻度强调的内容*。
显示效果:
这里是 需要轻度强调的内容。
左右各一个星号。中文字体的斜体效果有时不明显,日常中文笔记通常使用粗体更直观。
6.3 粗体加斜体
***特别强调的内容***
显示效果:
特别强调的内容
这种写法可以了解,但一篇文章里不要到处使用,否则重点反而不明显。
6.4 删除线:常见扩展
~~这条旧结论已经不再使用。~~
在支持删除线的平台上,会显示为:
这条旧结论已经不再使用。
左右各两个波浪号 ~。删除线适合保留被修正的旧说法,但正式文章中的无用内容通常直接删去更清楚。
6.5 下划线、高亮和颜色不是统一的基础语法
下面这些写法不要默认认为处处有效:
==高亮文字==
++带下划线的文字++
部分平台支持其中某种扩展,其他平台可能原样显示符号。__文字__ 在常见 Markdown 规则中表示粗体,不表示下划线。
如果你希望文章更容易迁移,先用标题、粗体和引用表达层次。文字颜色、背景色和字号通常交给主题控制。
7. 列表:表达并列项目、步骤和层级
7.1 无序列表
无序列表适合没有先后顺序的项目。
原始写法:
我准备学习以下内容:
- Java 基础
- Linux 命令
- 数据结构
显示效果:
我准备学习以下内容:
- Java 基础
- Linux 命令
- 数据结构
每项单独一行,短横线后面留一个空格。也可以使用 * 或 + 作为标记,但同一份文档中统一使用 - 更容易维护。
7.2 有序列表
有序列表适合操作步骤。
1. 创建 Markdown 文件。
2. 输入文章内容。
3. 保存文件。
4. 打开预览并检查。
显示效果:
- 创建 Markdown 文件。
- 输入文章内容。
- 保存文件。
- 打开预览并检查。
数字后面使用英文句点 .,句点后面留一个空格。
7.3 为什么有人把每项都写成 1.
下面的写法,在常见解析器中也能渲染为连续编号:
1. 创建文件。
1. 输入内容。
1. 检查预览。
这是因为渲染器会为同一个有序列表连续编号。它通常使用第一项的数字决定起始编号,不把后面每一项的源数字都当成独立指定的序号。
初学时仍建议写 1.、2.、3.,因为直接阅读源文件更清楚。如果编号本身必须原样保留,例如试题编号,应额外检查渲染结果。
7.4 嵌套列表
原始写法:
- 编程学习
- Java
- C
- 工具学习
- Vim
- Git
显示效果:
- 编程学习
- Java
- C
- 工具学习
- Vim
- Git
子项目向右缩进,就表示它属于上一层项目。以上简单例子每层缩进四个普通空格,便于初学时统一操作。
更准确地说,列表里的续行和子内容要相对父项目的正文位置缩进;遇到 10.、更长编号或者复杂嵌套时,需要注意对齐,不能机械认为所有情况都只加四个空格。
不要用很多层嵌套把文章变成迷宫。如果层级越来越深,考虑拆成小标题。
7.5 在一个列表项中写第二段
1. 创建练习文件。
文件名使用 `markdown-practice.md`,保存时确认扩展名正确。
2. 输入第一篇笔记。
解释:
- 第二段前面有空行。
- 第二段相对左边界缩进三个空格,与
1.后面的正文起点对齐。 - 这样它仍然属于第一个列表项。
如果去掉缩进,第二段可能变成列表之外的普通段落。
7.6 在列表项中放代码块
原始写法如下,外层示例框只是为了展示里面的三个反引号:
1. 查看当前目录。
```bash
pwd
```
2. 查看当前目录中的文件。
```bash
ls
```
代码块的开始行、内容行和结束行,都要一起缩进,才能保持在对应列表项里。代码块的完整用法见第 12 节。
7.7 列表前后空一行
推荐:
今天的目标如下:
- 完成笔记。
- 练习示例。
明天继续学习。
列表项目之间不一定需要空行;如果每项很长,或包含多个段落,可以用空行使它们更易读。
8. 任务列表:记录完成情况
任务列表属于常见扩展。原始写法:
- [x] 创建练习文件。
- [x] 学习标题语法。
- [ ] 学习图片插入。
- [ ] 完成一篇文章。
在支持任务列表的平台上,显示为:
- 创建练习文件。
- 学习标题语法。
- 学习图片插入。
- 完成一篇文章。
拆开看:
| 部分 | 含义 |
|---|---|
- |
无序列表标记,后面有空格 |
[ ] |
尚未完成,方括号中有一个空格 |
[x] |
已完成,使用字母 x |
| 标记后面的空格 | 把状态标记与任务文字分开 |
某些网页可以直接点击复选框;有些预览只能显示,不能点击修改。不能点击时,直接在源文件中把 [ ] 改成 [x]。
不要把任务状态写成 [],它少了中间的空格。
9. 引用:突出一段说明或摘录
9.1 最基本的引用
> 这一段用于补充说明:保存文件后,还需要检查预览。
显示效果:
这一段用于补充说明:保存文件后,还需要检查预览。
引用通常显示为带竖线、缩进或背景色的区域,具体外观取决于主题。
9.2 多行与多段引用
> 这是引用的第一段。
>
> 这是引用的第二段。
中间那一行只有 >,表示引用内部的空段落分隔。
为了避免引用范围不清楚,建议引用中的每行都写上 >;结束引用后,空一行再写普通正文。
9.3 引用内部也能包含格式
> **检查提示:**
>
> - 图片路径是否正确?
> - 代码块是否已经结束?
> - 链接能否打开?
显示效果:
检查提示:
- 图片路径是否正确?
- 代码块是否已经结束?
- 链接能否打开?
9.4 嵌套引用
> 第一层引用。
>
> > 第二层引用。
可以使用,但普通文章通常不需要很多层。
9.5 引用格式不会自动完成文献标注
> 只负责显示为引用区域。引用他人原话时,作者、出处和链接仍然需要自己注明;学术参考文献编号也不会因为使用 > 自动生成。
10. 分隔线:分开不同内容
原始写法:
上一部分内容。
---
下一部分内容。
三个短横线单独占一行,可以显示为水平分隔线。也有 ***、___ 等写法,初学时统一使用 --- 即可。
10.1 为什么建议分隔线上下空一行
注意下面的源文字:
这是一行文字
---
它可能被识别为另一种二级标题写法,而不是“正文后面加分隔线”。
因此,如果你的目的是分隔内容,写成:
这是一行文字。
---
不要每个小段后面都放分隔线。章节标题和正常段间距已经能表达很多层次。
11. 行内代码:给命令、文件名和变量一个清晰边界
11.1 什么情况下使用行内代码
在一句话中提到以下内容时,可以使用行内代码:
- 命令,例如
pwd。 - 文件名,例如
article.md。 - Java 方法,例如
System.out.println()。 - 变量名,例如
count。 - 按键或 Vim 命令,例如
Esc、:wq。
原始写法:
在终端输入 `pwd`,可以查看当前工作目录。
数组 `numbers` 中保存了三个整数。
显示效果:
在终端输入 pwd,可以查看当前工作目录。
数组 numbers 中保存了三个整数。
11.2 两边使用一个反引号
行内代码用左右各一个反引号包围,不是单引号,也不是三个反引号。
它通常显示为等宽字体,并带有与正文不同的背景或边界。
11.3 行内代码中的 Markdown 标记通常按文字显示
例如:
标题的写法是 `# 标题`。
这里的 # 标题 会作为语法示例出现,不会变成文章中的新标题。
11.4 想展示反引号本身,怎么办
可以用两个反引号包住包含一个反引号的内容:
`` `变量名` ``
它展示的是带反引号的文字 `变量名`。
这是编写 Markdown 教程时常用的方法。日常笔记中记住一个反引号的基本写法就够了。
11.5 行内代码不适合放多行程序
多行 Java、C 或终端输出,应使用下面的代码块。不要把整段程序硬塞在一对行内反引号之间。
12. 代码块:技术文章中最常用的语法之一
12.1 三个反引号开始,三个反引号结束
下面是应当写入文件的完整内容:
```java
public class Main {
public static void main(String[] args) {
System.out.println("Hello, Markdown!");
}
}
```
显示效果:
public class Main {
public static void main(String[] args) {
System.out.println("Hello, Markdown!");
}
}
逐行理解:
- 开头的三个反引号表示“代码块开始”。
java是语言标识,用于提示支持高亮的平台按 Java 着色。- 中间放代码。
- 结尾的三个反引号表示“代码块结束”。
开始围栏和结束围栏通常各自独占一行。初学时让它们从行首开始写,列表内部则按照列表要求整体缩进。
12.2 java 不会帮你执行程序
代码块只是展示内容。写上 java 不会调用 Java 编译器,写上 bash 也不会在读者的电脑上执行命令。
能不能运行代码,是某些编辑器或交互平台另外提供的功能。
12.3 常用语言标识
| 要展示的内容 | 常见标识 |
|---|---|
| Java 代码 | java |
| C 代码 | c |
| Python 代码 | python |
| JavaScript 代码 | javascript 或 js |
| Bash 命令 | bash |
| PowerShell 命令 | powershell |
| Windows 批处理 | bat |
| HTML | html |
| CSS | css |
| JSON | json |
| YAML | yaml |
| SQL | sql |
| Markdown 源文字 | markdown |
| 普通输出或无需高亮的文字 | text |
具体支持哪些名字,由平台使用的高亮工具决定。即使没有识别语言,代码块通常仍能按原样显示。
12.4 命令与输出分开写
命令:
pwd
输出示例:
/home/student/notes
这比把命令和结果混在一起更适合初学者阅读。
如果文章里展示了 $ pwd,其中 $ 可能只是终端提示符;真正需要执行的通常是 pwd。写可复制教程时,最好直接提供没有提示符的命令。
12.5 代码块内部通常不解析粗体和标题
原始写法:
```text
# 这不会变成标题
**这不会变成粗体**
```
显示效果:
# 这不会变成标题
**这不会变成粗体**
这正适合展示源代码、配置文件和 Markdown 语法。
12.6 为什么后半篇文章都变成代码了
最常见的原因是忘记结束围栏:
```java
int count = 3;
下面本来应该是正文,但是代码块还没有结束。
从代码块的开始位置往下检查,补上一行三个反引号即可。结尾不要写成三个单引号,也不要在同一行追加说明文字。
12.7 要在代码框里展示三个反引号,怎么办
让外层围栏比里面的反引号序列更长。例如外层使用四个反引号,里面展示三个反引号:
````markdown
```java
int count = 3;
```
````
上面例子中的四反引号用于包住“一个三反引号代码块的源文字”。这一技巧能避免 Markdown 教程的示例框被提前结束。
也可以使用波浪号作为围栏:
~~~text
这里的内容按代码显示。
~~~
同一个代码块的开始和结束围栏,应使用同一种字符。初学时让两边数量也相同,最容易检查。
12.8 不要给可复制代码添加手写行号
下面的 1、2 会一起被复制,可能让程序报错:
1 int count = 3;
2 System.out.println(count);
应提供不带行号的实际代码。如果需要行号,优先使用网站主题的显示功能。
13. 链接:让读者跳转到网页或文件
13.1 最基本的链接
原始写法:
[查看 Markdown 规范](https://spec.commonmark.org/0.31.2/)
显示效果:
结构是:
[读者看到的文字](实际跳转地址)
方括号中是名称,圆括号中是地址。两部分之间不要插入额外空格。
13.2 链接文字尽量说明用途
比较下面两种写法:
[点击这里](https://spec.commonmark.org/0.31.2/)
[查看 CommonMark 语法规范](https://spec.commonmark.org/0.31.2/)
第二种让读者在点击前就知道会去哪里。
13.3 直接显示网址
一种兼容性较好的写法是用尖括号包围完整网址:
<https://example.com>
部分平台也会把裸写的网址自动转成链接,但这属于平台或扩展行为。需要可靠表达时,使用标准的方括号加圆括号写法。
example.com 在教程中作为示例域名,实际写文章时请替换为真正要引用的地址。
13.4 带可选标题的链接
[示例网站](https://example.com "访问示例网站")
双引号里的文字是可选的链接标题,有些浏览器会在鼠标悬停时显示。它不会替代方括号中的可见文字,也不应承载不可缺少的信息。
13.5 引用式链接
当同一个地址出现多次时,可以把链接定义集中写在文末:
可以阅读 [CommonMark 规范][cm]。
遇到语法疑问时,再查阅 [同一份规范][cm]。
[cm]: https://spec.commonmark.org/0.31.2/
这里的 cm 是自己取的标识。正文中的标识和定义中的标识要匹配。
这叫“引用式链接”,与学术文章的参考文献引用不是同一回事。
13.6 链接到同一目录下的文件
假设当前文件旁边有 java-notes.md:
[阅读 Java 笔记](./java-notes.md)
./ 表示当前目录;../ 表示上一级目录。
本地预览能打开的 .md 链接,发布后是否仍有效,取决于博客系统是否会把它改写成正确的网页地址。发布后要实际点击检查。
13.7 路径包含空格或括号时
新手最省事的方法是给文件使用简单名称,例如:
java-notes.md
array-example.png
如果地址确实包含空格,部分情况可用尖括号包围链接目标:
[阅读笔记](<./my notes.md>)
网页 URL 也可能需要正确编码。不要随意删除原网址中的字符;遇到复杂地址时优先使用浏览器复制的完整链接,并在预览中测试。
14. 图片:写法很短,路径需要仔细理解
14.1 图片比链接多一个感叹号
原始写法:

和链接对照:
[打开图片](./images/array-example.png)

第一行创建指向图片的链接;第二行请求直接显示图片。
本节的图片路径用于教学。只有对应图片文件真实存在,预览器才能显示它。
14.2 方括号中的文字是什么
方括号中是替代文字,通常称为 alt 文本。它可以帮助使用屏幕阅读器的人理解图片,也可能在图片加载失败时显示。
推荐描述图片包含的信息:

比下面的写法更有用:

替代文字通常不会自动成为图片下方的可见图注。需要图注时,在图片后空一行,另外写一段说明。
14.3 本地图片路径怎么找
假设文件布局如下:
| 文件路径 | 用途 |
|---|---|
notes/article.md |
当前文章 |
notes/images/array-example.png |
配套图片 |
notes/images/result.png |
配套图片 |
在 article.md 中,常见本地预览写法是:

读取方式是:从当前文章所在目录出发,进入 images 目录,寻找 array-example.png。
14.4 图片位于上一级目录时
另一种布局:
| 文件路径 | 用途 |
|---|---|
notes/java/article.md |
当前文章 |
notes/images/array-example.png |
配套图片 |
此时文章中的相对路径可以写成:

解释:先从 java 回到上一级 notes,再进入 images。
14.5 文件路径与网站地址要分清
| 写法 | 常见含义 |
|---|---|
./images/a.png |
相对位置;本地预览通常相对当前文件目录,网页中最终按页面 URL 或系统改写规则解析 |
../images/a.png |
先到上一级位置,再寻找图片 |
/images/a.png |
在普通网页中通常从网站域名根路径寻找 |
https://example.com/images/a.png |
完整网络图片地址 |
C:\Users\student\Pictures\a.png |
某台 Windows 电脑上的文件位置,其他访客无法凭这个路径读取图片 |
本地能显示,不保证发布后能显示。 博客生成器可能有自己的静态资源目录、页面资源或路径改写规则。
14.6 为什么不能只上传 .md 文件
Markdown 里的图片语法通常只保存“图片在哪里”,不会把图片文件的全部内容自动装进 .md 文件。
如果文章引用本地图片,你需要把图片一起放到目标系统能访问的位置,并确保发布后的地址正确。
复制一篇含有 ./images/a.png 的文章到新电脑,却不复制 images/a.png,图片就会缺失。
14.7 图片不显示,按这个顺序排查
- 目标图片文件是否真的存在?
- 文件名是否拼错?
.png、.jpg、.jpeg等扩展名是否一致?- 大小写是否完全一致,例如
Photo.png与photo.png? - 相对路径是否从正确位置出发?
- 发布时图片是否一起上传?
- 网络图片地址是否需要登录、已失效或限制外部访问?
建议路径使用 /,并且严格保持大小写一致。某些本地环境对大小写较宽松,部署环境可能严格区分。
14.8 如何设置宽度或图注
基础 Markdown 没有统一的图片宽度、居中和图注语法。
图注可以先这样写:

图 1:数组元素与下标的对应关系。
允许 HTML 的平台上,有时可以用:
<img src="./images/array-example.png" alt="数组示意图" width="480">
博客也可能提供专门的图片组件。应先使用目标系统支持的方法,不要假设 {width=480} 等扩展处处有效。
15. 表格:适合对照,不适合堆长段落
表格是常见扩展,例如 GFM 支持下面的写法。
15.1 一个完整的表格
原始写法:
| 命令 | 作用 | 使用位置 |
| --- | --- | --- |
| `pwd` | 查看当前工作目录 | 终端 |
| `ls` | 列出目录内容 | 终端 |
| `:w` | 保存当前文件 | Vim |
显示效果:
| 命令 | 作用 | 使用位置 |
|---|---|---|
pwd |
查看当前工作目录 | 终端 |
ls |
列出目录内容 | 终端 |
:w |
保存当前文件 | Vim |
15.2 三个部分分别做什么
- 第一行是表头。
- 第二行是分隔行,告诉解析器“这是一个表格”。
- 后面的行是数据。
竖线 | 分隔不同列。表头和分隔行的列数需要一致;为了避免丢失内容,每条数据也按相同列数填写。
分隔行每列统一使用至少三个短横线,是便于阅读、兼容常见工具的写法。
15.3 不用手工把源文件的每一列排得很齐
下面的源文字虽然不整齐,也可以形成表格:
| 名称 | 说明 |
| --- | --- |
| Java | 一种编程语言 |
| C | 一种编程语言 |
预览器负责排版。你可以整理源文件的空格以方便阅读,但不必为了凑齐中文宽度花很多时间。
15.4 控制列对齐
| 项目 | 状态 | 数量 |
| :--- | :---: | ---: |
| 标题 | 已完成 | 6 |
| 图片 | 待补充 | 2 |
显示效果:
| 项目 | 状态 | 数量 |
|---|---|---|
| 标题 | 已完成 | 6 |
| 图片 | 待补充 | 2 |
| 分隔行写法 | 表达的对齐方式 |
|---|---|
:--- |
左对齐 |
:---: |
居中 |
---: |
右对齐 |
--- |
使用默认对齐 |
实际样式仍可能受到网站 CSS 的影响。
15.5 表格里要显示竖线,怎么办
在 GFM 一类表格中,可以用反斜杠转义竖线:
| 运算符 | 说明 |
| --- | --- |
| `a \| b` | 按位或表达式 |
| `a \|\| b` | 逻辑或表达式 |
即使放在行内代码中,表格里的竖线也需要按照表格解析器的规则处理。上例是 GFM 的写法;迁移到其他平台时请检查效果。
15.6 表格中的限制
简单 Markdown 表格通常适合:短文字、数字、行内代码、粗体和链接。
不适合直接放入:
- 很长的整段文章。
- 多层列表。
- 多行代码块。
- 需要合并行列的复杂版式。
单元格内换行有时可以使用 <br>,但需要平台允许 HTML。复杂内容更适合拆成多个小节,而不是强行塞进一张表。
表格内部也不要随意空一整行,否则表格可能提前结束。
16. 转义:让特殊符号按原样显示
16.1 为什么需要转义
假设你想让读者看到:
*重点*
但直接在正文中写 *重点*,它会被当成斜体。
你可以在两个星号前面加反斜杠:
\*重点\*
显示效果:
*重点*
这里的反斜杠表示:这次把后面的星号当作普通字符。
16.2 常见情况
\# 这行不作为标题
\- 这行不作为列表
\[这不是一个链接\]
1\. 这里的编号作为普通文字保留
无需给所有标点都加反斜杠。只有某个字符正在触发你不希望出现的格式时,才需要处理。
16.3 展示语法时,行内代码往往更方便
比较:
标题写成 \# 标题。
标题写成 `# 标题`。
第二种更适合技术说明,因为读者能清楚看到哪些字符属于语法。
16.4 代码块中一般不需要 Markdown 转义
在代码块里,通常直接写原始代码即可。不要因为担心星号被解析,就给 Java、C 或正则表达式随意加反斜杠,否则可能改变代码本身。
同时要区分两层规则:Markdown 的转义用于排版;程序语言、JSON 或正则表达式的转义由它们自己的语法决定。
17. 目录和页内跳转
17.1 标题是目录的基础
多数自动目录工具会扫描 #、##、### 等标题,再生成可点击目录。
所以,先把标题层级写清楚,比先寻找“生成目录按钮”更重要。
17.2 [TOC] 并不是通用写法
有的软件支持:
[TOC]
有的软件不支持,会直接显示这几个字符。[[TOC]]、[toc] 等写法也可能属于某个平台自己的扩展。
如果没生成目录,不一定是你少打了符号,也可能是平台根本没有这项功能。
17.3 手写页内链接
在许多常见平台上,下面的英文标题会获得类似 installation 的锚点:
[跳到安装部分](#installation)
## Installation
其中 #installation 表示本页面中某个位置的标识,不是一个外部网址。
锚点生成规则不是所有 Markdown 平台都一致。 标点、空格、中文标题、重复标题,尤其容易出现差异。
17.4 更稳妥的做法
- 先在目标平台显示文章。
- 找到目标标题旁边的链接图标,或平台提供的标题链接。
- 复制实际生成的锚点。
- 放入目录链接中。
- 点击验证是否跳转到正确位置。
如果修改了标题,也要检查原有的页内链接是否仍然有效。
17.5 自动目录和博客菜单不是同一个东西
- 文章目录:跳转到这一篇文章中的不同小节。
- 网站菜单:跳转到首页、分类页、关于页等不同页面。
- 编辑器大纲:帮助作者在编辑器中定位标题。
它们可能都使用标题或配置数据,但属于不同功能。
18. 脚注:把补充说明放在文末
脚注不是所有 Markdown 平台都支持。常见写法如下:
这份笔记使用 UTF-8 编码。[^encoding]
[^encoding]: UTF-8 是一种常用的字符编码方式,可以表示中文等字符。
支持脚注的渲染器通常会在正文生成一个小编号,并把对应说明放到文末或脚注区域。
18.1 脚注的两个部分
| 部分 | 用途 |
|---|---|
[^encoding] |
正文中的脚注引用 |
[^encoding]: 说明内容 |
对应的脚注定义 |
encoding 是自己选择的标识,引用与定义必须匹配。最终显示的数字通常由渲染器生成,不必与你写的标识相同。
18.2 脚注适合什么内容
适合解释术语、提供不影响主线的小补充,或注明某个背景条件。
如果一段说明对理解正文必不可少,应直接写入正文,不要让读者频繁跳到文末。
18.3 脚注不等于参考文献管理系统
脚注语法不会自动把文章整理成 GB/T 7714,也不会自动核对论文信息、消除重复文献或维护完整的学术引用关系。
如果需要正式的引文管理,应使用目标写作工具支持的文献处理流程。单纯学习 Markdown 时,先理解脚注的引用与定义如何配对。
参考:GitHub 基本文字与格式语法。
19. 数学公式:需要平台支持
公式功能常由 MathJax、KaTeX 等渲染工具提供,不属于所有 Markdown 解析器都具备的基础功能。
下面介绍常见的美元符号写法。请先在你的编辑器和最终发布平台上试一个最简单的公式。
19.1 行内公式
原始写法:
当 $x = 2$ 时,$x^2 = 4$。
在支持这种公式语法的平台中,数学表达式会出现在同一行正文中。
美元符号包围的是公式,普通中文解释写在外面。为了减少解析差异,初学时不要在行内公式的美元符号内侧额外留空格。
19.2 独立公式
原始写法:
样本均值可以写为:
$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i
$$
其中,$n$ 表示样本数量。
把 $$ 各自放在单独一行,公式单独占一个区域;公式前后空一行,便于区分正文。
公式表示:把全部样本值加起来,再除以样本数量。
19.3 常用公式语法
| 目的 | 公式内部写法 | 含义 |
|---|---|---|
| 上标 | x^2 |
x 的平方 |
| 多字符上标 | x^{10} |
x 的十次方 |
| 下标 | x_i |
带下标 i 的 x |
| 多字符下标 | x_{max} |
下标为 max |
| 分数 | \frac{a}{b} |
a 除以 b |
| 平方根 | \sqrt{x} |
x 的平方根 |
| 求和 | \sum_{i=1}^{n}x_i |
从 i 等于 1 加到 n |
| 积分 | \int_0^1 x\,dx |
从 0 到 1 对 x 积分 |
| 希腊字母 | \alpha、\beta、\theta |
α、β、θ |
| 不等于 | a \ne b |
a 不等于 b |
| 小于等于 | a \le b |
a 小于等于 b |
| 乘号 | a \times b |
a 乘以 b |
| 公式中的文字 | \text{mean} |
以文字形式排版 mean |
表中的写法需要放在受支持的公式区域里。在普通段落中直接写 \frac{a}{b},不会自动得到分数。
19.4 为什么有时需要花括号
比较:
x^10
x^{10}
没有花括号时,指数通常只作用于紧接着的一个符号;加上花括号,才能把 10 作为一个整体。
下标也是同样的道理:多字符内容使用 {...} 包起来。
19.5 多行公式
支持相应 LaTeX 数学语法的平台可以写:
$$
\begin{aligned}
y &= 2x + 1 \\
y &= 2 \times 3 + 1 \\
y &= 7
\end{aligned}
$$
其中:
aligned表示一个对齐环境。&标出对齐位置。- 两个反斜杠
\\表示公式内部换行。
这与第 5 节正文行尾的单个反斜杠不是同一层规则。
19.6 一个小矩阵
$$
A = \begin{bmatrix}
1 & 2 \\
3 & 4
\end{bmatrix}
$$
& 分隔同一行中的元素,\\ 分隔矩阵的不同行。
19.7 公式不显示时
依次检查:
- 目标平台是否支持公式,是否需要打开设置?
- 美元符号是否配对?
- 是否误把公式放进了普通代码块?
- 反斜杠、花括号或环境名称是否写错?
- 当前数学渲染工具是否支持所用命令?
教程把公式源文字放在代码框中,是为了让你看清写法。实际希望显示公式时,要把代码框里面的 $ 或 $$ 写入正文,不要连同最外面的示例代码围栏一起保留。
参考:GitHub 数学表达式说明。
20. Mermaid 流程图:用文字描述图形
Mermaid 是独立的图表描述工具。某些 Markdown 平台会识别标记为 mermaid 的代码块,并将内容渲染成图。
20.1 一个有判断分支的例子
原始写法:
```mermaid
flowchart TD
A["保存文章"] --> B{"预览是否正确"}
B -->|否| C["修改内容"]
C --> A
B -->|是| D["发布文章"]
```
支持 Mermaid 的平台可以把它显示为:
flowchart TD
A["保存文章"] --> B{"预览是否正确"}
B -->|否| C["修改内容"]
C --> A
B -->|是| D["发布文章"]
如果这里看到的仍是代码,说明当前预览环境没有对 Mermaid 进行图形渲染;源文字可以保留,换到支持它的平台再预览。
20.2 逐项解释
| 写法 | 含义 |
|---|---|
flowchart TD |
绘制流程图,方向从上到下 |
A、B、C、D |
节点标识,用来连接节点 |
["保存文章"] |
一个矩形节点及其文字 |
{"预览是否正确"} |
一个判断节点及其文字 |
--> |
带方向的连接线 |
| 箭头上的“是”“否” | 判断结果对应的分支标签 |
初学时,节点标识使用简单的英文字母,显示文字使用带引号的中文即可。
20.3 什么时候适合画图
适合说明有分支、重复、依赖关系的过程。只有两三个线性步骤时,普通有序列表通常已经足够清楚。
流程图不是 Markdown 文件的必需部分,可以等基础语法熟练后再学。
参考:Mermaid 流程图语法。
21. HTML 和特殊提示框:了解边界即可
21.1 Markdown 文档有时可以混用 HTML
例如,在允许 HTML 的平台上:
这一行文字<br>换到下一行。
也可能使用 HTML 实现上标、下标或图片尺寸:
H<sub>2</sub>O
x<sup>2</sup>
平台可能过滤 HTML,允许的标签和属性也可能不同。不要把某个编辑器里可用的写法,直接当成所有网站的通用能力。
21.2 HTML 注释
<!-- 这里提醒自己:之后补充一个实际例子。 -->
支持 HTML 注释的渲染器通常不会把它显示在正文中。但注释仍存在于源文件中,也可能保留在网页源代码中,不属于保密机制。
21.3 折叠内容
某些平台支持:
<details>
<summary>点击查看补充说明</summary>
这里放补充说明。内部 Markdown 能否继续解析,要看平台。
</details>
这种功能适合很长的输出或补充内容,不应把读者必须知道的核心步骤藏起来。
21.4 GitHub 风格提示框
部分平台支持如下扩展:
> [!NOTE]
> 这是补充说明。
在不支持这种扩展的平台上,它可能只是普通引用,并直接显示 [!NOTE]。
想获得更容易迁移的写法,可以使用:
> **说明:** 这是补充说明。
21.5 不要为了少量颜色效果过早引入复杂写法
一篇清楚的文章可以只使用标题、段落、列表、粗体、代码、链接和图片。
先把内容和结构写清楚,确实需要某种特殊效果时,再确认平台支持的方法。
22. 博客文章开头的 Front Matter 是什么
这一节用于帮助你识别博客文件开头的配置。它属于博客系统知识,不是写普通 Markdown 文件的必备条件。
22.1 文章元数据与正文
一些博客系统会在 .md 文件最开头放一段元数据,称为 Front Matter。它描述文章标题、日期、草稿状态等信息,后面才是 Markdown 正文。
以 Hugo 支持的 YAML 格式为例:
---
title: "Java 数组学习笔记"
date: 2026-09-23T20:00:00+08:00
draft: true
tags:
- Java
- 数组
---
## 数组是什么
数组可以保存多个相同类型的元素。
这是一个说明格式的例子,不是在确认你的博客使用 Hugo,也不意味着其他博客系统都接受相同字段。
22.2 怎样阅读这段配置
| 内容 | 在此 Hugo 示例中的作用 |
|---|---|
第一行与第二处 --- |
包围 YAML 元数据 |
title |
文章标题 |
date |
文章日期;示例时间包含时区 |
draft: true |
标记为草稿;普通构建通常不包含草稿,构建参数可以改变这一行为 |
tags |
标签,具体显示还受站点配置和主题影响 |
| 结束分隔符之后 | 文章正文 |
draft: false 只是改变草稿状态,不会替你上传文件或完成网站部署。
22.3 YAML 与 TOML 不要混用
Hugo 等工具也可能使用 TOML:
+++
title = "Java 数组学习笔记"
draft = true
tags = ["Java", "数组"]
+++
上面展示的是带边界标记的 TOML Front Matter。内部使用 =;YAML 示例使用 :。如果系统已经自动生成了一种格式,沿用它的写法最省事。
22.4 文件夹、分类和标签不是自动等价的
把文章放进名为 java 的目录,表达的是文件存放位置。网页上是否出现“Java 分类”、菜单是否变化、URL 是否变化,取决于博客的内容组织和配置规则。
categories、tags 等字段是否可用、如何显示,也由目标系统决定。
不要仅凭文件夹名称,判断网页一定会生成某个分类页。
22.5 普通预览和博客预览可能不同
普通 Markdown 预览器可能原样显示元数据,或把分隔符解释成其他结构;博客系统则可能先读取元数据,再渲染正文。
因此,博客文章最终要在博客自己的预览中检查。Front Matter 格式应参考目标系统文档,例如 Hugo Front Matter 文档。
23. 怎样查看写作效果
23.1 最基本的检查方式
打开 .md 源文件,旁边打开 Markdown 预览,做一次很小的修改,例如把一行普通文字改成:
## 一个测试标题
观察预览是否同步出现标题。这样可以确认你打开的是同一份文件,且当前界面确实在渲染 Markdown。
23.2 VS Code 的预览快捷键
以下是官方文档中的默认快捷键;如果你修改了键位,以自己的设置为准。
| 操作 | Windows / Linux | macOS |
|---|---|---|
| 打开 Markdown 预览 | Ctrl + Shift + V |
Command + Shift + V |
| 打开侧边预览 | 先按 Ctrl + K,松开,再按 V |
先按 Command + K,松开,再按 V |
第二行是先后按的组合,不是三个键始终一起按住。
也可以在命令面板中搜索 Markdown: Open Preview to the Side,中文界面可搜索包含“Markdown”和“预览”的命令。
VS Code 自带基础 Markdown 预览,不必为了第一次预览先安装插件。参考:VS Code 的 Markdown 官方说明。
23.3 在 Vim 中编辑时怎么看
普通终端 Vim 主要负责编辑源文字。语法高亮可以帮助识别标记,但它本身不等同于网页式预览。
简单做法是:
- 在 Vim 中编辑文章。
- 按
Esc,输入:w并回车,保存。 - 用支持 Markdown 预览的软件打开同一份文件,或查看博客预览页面。
- 修改后再次保存,确认预览更新。
不要同时在两个编辑器里修改同一个文件却不保存,避免混淆哪一份修改才是最新的。
如果文件在服务器上,要确认预览软件打开的确实是那份远程文件,或者是刚刚同步的副本。
23.4 双击 .md 不一定直接看到排版效果
双击文件后打开哪个软件,由系统文件关联决定。它可能打开记事本、Vim、VS Code,也可能打开专门的阅读器。
看到 # 和反引号,通常说明当前是源文字编辑界面。需要寻找“预览”入口,而不是马上认为文件坏了。
23.5 本地预览正确后,还要检查目标网站
本地预览主要确认正文语法。网站预览还能确认:
- 主题是否重复显示文章标题。
- 图片最终地址是否正确。
- 表格是否太宽,手机上是否易读。
- 数学公式、流程图等功能是否启用。
- 文章目录和页内链接是否正常。
预览与发布是不同步骤。保存一个 .md 文件,不一定自动更新互联网上的文章。
24. 一次完整的 Markdown 写作流程
第一步:确定这篇文章解决什么问题
先用一句话写清楚目标,例如:
这篇文章说明 Java 数组如何声明、访问和遍历。
如果一句话中塞进了太多主题,先缩小范围。一个小问题讲清楚,比多个大主题各写两句更有用。
第二步:创建文件并拟好名称
例如 java-array-notes.md。先保存文件,确认位置和扩展名。
如果你在既有博客项目里写作,使用项目已有的文章创建流程,保留它生成的 Front Matter 和目录约定。
第三步:只写标题骨架
# Java 数组学习笔记
## 1. 数组是什么
## 2. 如何创建数组
## 3. 如何访问元素
## 4. 如何遍历数组
## 5. 常见错误
此时先检查逻辑顺序,暂时不用处理字体和图片大小。
第四步:在每个标题下填普通文字
一段集中解释一个意思。如果内容是并列项目,改成列表;如果内容是先后步骤,改成有序列表。
不要把整篇文章写成一连串没有解释的代码块。代码上下应说明它解决什么问题、读者应关注什么。
第五步:加入示例和结果
技术笔记可以采用:
- 先解释目的。
- 给出可以复制的代码或命令。
- 展示必要的输出。
- 说明输出为什么是这样。
- 提醒与当前问题直接相关的常见错误。
示例应尽量短,能够单独说明一个知识点。
第六步:补充链接和图片
优先加入真正帮助理解的材料。图片出现后,用一两句话说明读者应该看哪里;链接文字说明它的用途。
如果引用了本地图片,确认图片也保存在文章配套目录或博客要求的资源目录中。
第七步:保存并检查预览
先查看结构,再检查细节:
- 标题层级是否合理?
- 段落是否意外连在一起?
- 列表和代码块是否越出了预期范围?
- 图片和链接是否有效?
- 手机上是否出现过宽表格或长代码行?
第八步:通过网站已有流程发布
对于静态博客,通常还需要构建或触发部署;对于在线编辑平台,可能需要点击发布。具体操作取决于你的系统。
教程不提供一个假定适用于所有博客的“万能发布命令”。应沿用项目实际使用的命令和流程。
第九步:打开正式页面检查
确认读者访问的页面确实更新,再检查链接、图片和特殊格式。编辑器里正确不等于最终网页一定正确。
第十步:以后修改时,继续编辑源文件
找到原来的 .md 文件,修改、保存、预览,再按同一流程更新发布。
一般不建议把博客生成后的 HTML 当作日常文章源文件直接修改,因为后续重新构建可能覆盖这些改动。
25. 一篇可直接复制的完整文章示例
下面是一篇不依赖图片、公式或流程图的入门技术笔记。它可以作为独立 .md 文件使用。
复制代码框内部的全部内容。外面用于展示示例的四个反引号不属于文章;里面包围 Java 和终端内容的三个反引号属于文章。
如果你的博客需要 Front Matter,先保留博客生成的元数据,再粘贴正文;如果主题已自动显示主标题,可以根据预览移除示例中的一级标题。
# Java 数组学习笔记
这篇笔记记录 Java 数组的基本用法:创建数组、访问元素、遍历元素,以及检查数组下标。
## 1. 数组是什么
数组可以保存多个相同类型的元素。下面的数组保存了三个整数:
```java
int[] numbers = {10, 20, 30};
```
其中:
- `int[]` 表示整数数组类型。
- `numbers` 是引用这个数组的变量名。
- `{10, 20, 30}` 给出了数组的三个初始元素。
## 2. 数组下标从 0 开始
| 下标 | 对应元素 |
| ---: | ---: |
| 0 | 10 |
| 1 | 20 |
| 2 | 30 |
因此,`numbers[0]` 访问第一个元素,`numbers[2]` 访问第三个元素。
**数组长度为 3,但最后一个有效下标是 2。**
## 3. 一个完整程序
将下面的程序保存为 `ArrayDemo.java`:
```java
public class ArrayDemo {
public static void main(String[] args) {
int[] numbers = {10, 20, 30};
for (int i = 0; i < numbers.length; i++) {
System.out.println("下标 " + i + ",元素 " + numbers[i]);
}
}
}
```
循环中的 `i` 依次取 `0`、`1`、`2`,因此程序输出三行。
## 4. 编译和运行
如果电脑已经安装并配置好 JDK,在 `ArrayDemo.java` 所在目录中依次执行:
```bash
javac ArrayDemo.java
java ArrayDemo
```
输出:
```text
下标 0,元素 10
下标 1,元素 20
下标 2,元素 30
```
## 5. 一个常见错误
下面的访问超出了这个数组的有效下标范围:
```java
System.out.println(numbers[3]);
```
> **检查方法:** 对于长度为 `n` 的非空数组,有效下标是 `0` 到 `n - 1`。本例中 `n` 等于 `3`,所以有效下标是 `0`、`1`、`2`。
在本例的循环中,条件应写为 `i < numbers.length`。
## 6. 自测练习
- [ ] 把数组改成 `{5, 8, 13, 21}`。
- [ ] 在运行前,先写出你预测的输出。
- [ ] 运行程序,对比预测是否正确。
- [ ] 解释为什么循环条件不能写成 `i <= numbers.length`。
## 7. 今天记住的内容
数组中的元素通过下标访问,下标从 `0` 开始。遍历数组时,需要让下标始终处于有效范围内。
这篇示例同时使用了标题、段落、列表、表格、行内代码、代码块、引用和任务列表。表格、任务列表属于常见扩展;目标平台不支持时,可以改成普通列表。
26. 两份可以重复使用的写作模板
26.1 学习笔记模板
# 主题名称
用两三句话说明:这篇笔记记录什么,读完能够解决什么问题。
## 1. 核心概念
解释最重要的概念,必要时给一个简短例子。
## 2. 基本用法
按步骤说明操作或语法。
## 3. 完整示例
提供一个足够小、能够独立理解的示例。
## 4. 结果与解释
展示必要结果,并解释它与前面概念的关系。
## 5. 常见错误
写出错误表现、原因与修改方法。
## 6. 练习
- 练习一。
- 练习二。
## 7. 参考资料
- [资料名称](https://example.com)
26.2 排错记录模板
# 问题名称
## 1. 我想完成什么
简要说明目标。
## 2. 使用环境
- 操作系统:
- 软件及版本:
- 相关文件:
## 3. 出现了什么现象
写清楚实际结果和预期结果的差别。
## 4. 如何复现
1. 第一步。
2. 第二步。
3. 出现问题。
## 5. 原因分析
列出已经确认的事实,把尚未验证的猜测单独说明。
## 6. 解决方法
1. 修改什么。
2. 为什么这样修改。
3. 如何确认生效。
## 7. 验证结果
记录复测步骤和结果。
## 8. 参考资料
- [资料名称](https://example.com)
模板中的提示文字和示例链接需要替换。某一节没有实际内容时可以删除,不必为了凑齐模板写空话。
27. 常见错误与排查方法
27.1 快速对照表
| 看到的问题 | 常见原因 | 如何处理 |
|---|---|---|
#标题 没变成标题 |
# 后没有空格 |
改成 # 标题 |
| 看起来有井号,却无法识别标题 | 使用了全角 # |
改成英文半角 # |
| 标题被当成普通文字 | 写了七个以上的 #,或位于代码块中 |
检查级别和代码块边界 |
| 段落全连在一起 | 只回车,没有空行;平台折叠了软换行 | 段落之间留一条空行 |
| 回车后仍不换行 | 没有使用硬换行语法 | 使用两个行尾空格,或平台支持的行尾反斜杠 |
| 本来想写正文,却出现代码样式 | 段首有四个空格,或上方代码块未结束 | 检查缩进和结束围栏 |
| 后面整篇文章都变成代码 | 忘记关闭代码块 | 补上匹配的结束围栏 |
| 三个符号看起来正确,仍无法形成代码块 | 用了单引号而非反引号 | 检查字符本身 |
| 代码块有边框但没有颜色 | 没写语言标识,或平台不支持高亮 | 添加 java 等正确标识,检查平台功能 |
| 粗体没有生效 | 标记没配对,或内部两端多了空格 | 使用 **重点**,并检查邻近字符和平台差异 |
| 无序列表没有出现 | 写成了 -项目 或中文破折号 |
改成 - 项目 |
| 子列表变成普通段落 | 缩进不足或层级不一致 | 对照父列表正文位置调整缩进 |
| 任务列表没变成复选框 | 平台不支持,或写成 [] |
使用 - [ ] 任务,确认扩展支持 |
| 引用范围比预期更长 | 引用后的段落未明确分开 | 引用结束后空一行再写正文 |
| 链接直接显示源码 | 全角括号、标记缺失或定义缺失 | 检查 [文字](地址) 和引用式链接定义 |
| 图片显示成文字链接 | 少了开头的 ! |
使用  |
| 图片出现破图图标 | 路径、文件名或访问条件有问题 | 按第 14 节逐项检查 |
| 本地图片正常,网页图片失效 | 发布地址与本地路径不一致,或没有上传资源 | 检查网站资源规则和最终 URL |
| 表格没有形成 | 缺少分隔行,或平台不支持表格 | 补齐第二行并确认扩展支持 |
| 表格错列 | 单元格内容含未转义的竖线 | 按平台规则转义,或移到表格外展示 |
[TOC] 原样显示 |
没有启用对应目录功能 | 使用平台目录功能或手写页内链接 |
| 数学公式原样显示 | 未支持公式,或公式被包在代码块中 | 确认公式功能和所在位置 |
| Mermaid 只显示代码 | 没有对应图表渲染功能 | 使用支持 Mermaid 的平台,或保留为代码示例 |
| 博客文章标题出现两次 | 主题标题和正文一级标题重复 | 检查主题输出,按实际情况保留一处 |
| 保存文章后网站没变化 | 保存没有触发更新发布,或查看了旧内容 | 确认部署流程与最终页面 |
| 中文出现乱码 | 文件被按不匹配的字符编码读取 | 确认编辑器读取和保存编码,通常统一使用 UTF-8 |
27.2 推荐的排查顺序
先判断问题范围:
- 只有一个符号异常:优先检查半角字符、空格和配对。
- 从某一行开始后面全异常:优先检查代码围栏、HTML 块和列表缩进。
- 同一段在 A 软件正常、B 软件异常:优先检查扩展支持和渲染设置。
- 只有发布后异常:优先检查网站资源路径、构建和主题。
27.3 用最小例子定位问题
如果一篇长文中某张表格不显示,先新建一个临时练习文件,只放这张表格。
- 单独能显示:问题可能来自前文,例如没结束的代码块。
- 单独仍不能显示:问题可能来自表格自身或平台功能。
每次只修改一类问题,然后重新预览。一次改十处,反而难以判断是哪一处起了作用。
28. 让文章更好读的写作习惯
28.1 每一节回答一个明确问题
例如“如何声明数组”比“其他内容”更容易让读者判断是否需要阅读。
28.2 先解释用途,再给语法
读者先知道“为什么要用”,更容易理解后面的符号。
28.3 代码旁边解释关键点
不要逐字翻译所有代码,只解释本节真正需要读者理解的部分。完整程序要能看出文件名、运行入口和必要条件。
28.4 粗体只标真正的重点
如果每一行都加粗,视觉上就没有重点。通常强调关键词或一个关键结论即可。
28.5 用表格表达可以逐项比较的内容
命令与作用、错误与原因、文件与用途适合表格;连续推理和长篇解释更适合段落。
28.6 在正文中说明图片的意义
“见下图”往往不够。可以写成“图中下标从 0 开始,因此第三个元素对应下标 2”,让图片直接服务于解释。
28.7 保持源文件也能阅读
统一标题层级、列表标记和空行习惯。Markdown 的一个优势是:即使暂时没有预览,别人也能读懂源文字的大致结构。
28.8 区分事实、示例和自己的判断
实际运行结果与假设输出要分清;引用资料给出链接;暂未验证的猜想就写成“可能的原因”。这对技术排错笔记尤其有用。
28.9 发布前做一次精简检查
- 标题是否清楚说明主题?
- 开头是否说明本文解决什么问题?
- 章节顺序是否符合读者理解顺序?
- 示例中的文件名、变量名和输出是否一致?
- 图片是否存在,链接是否有效?
- 特殊扩展在目标平台是否可用?
- 是否残留“稍后补充”等占位文字?
- 正式页面是否已更新?
29. 练习:自己写一次,再对照答案
练习一:写出文章层级
要求:文章标题为“我的 Linux 笔记”,包含“目录操作”和“文件操作”两个二级标题;“目录操作”下包含“查看当前位置”这个三级标题。
参考答案:
# 我的 Linux 笔记
## 目录操作
### 查看当前位置
## 文件操作
检查:不要把不同层级全部写成一个 #。
练习二:区分两个段落与段内换行
要求:先写两个独立段落,再写同一段中的两行联系信息。
参考答案:
今天学习了标题。
明天继续学习列表。
姓名:小林\
身份:学生
答案的最后两行使用 CommonMark 风格的行尾反斜杠。若平台不支持,换成两个行尾空格等受支持写法。
练习三:在一句话里同时使用粗体与行内代码
要求:“一定要保存文件”使用粗体,:w 使用行内代码。
参考答案:
修改后,**一定要保存文件**;在 Vim 中可以使用 `:w`。
检查:粗体用星号,行内代码用反引号。
练习四:修好一份列表
有问题的内容:
-创建文件
-写入正文
-查看预览
参考答案:
- 创建文件
- 写入正文
- 查看预览
再把它改为有序步骤:
1. 创建文件。
2. 写入正文。
3. 查看预览。
练习五:展示 Java 代码
要求:让 System.out.println("Hello"); 出现在 Java 代码块中,并在代码块后面写普通正文“这行代码会输出 Hello。”
参考答案:
```java
System.out.println("Hello");
```
这行代码会输出 Hello。
检查:普通正文是否回到了代码块之外?如果没有,检查结束围栏。
练习六:判断图片相对路径
已知:
| 文件 | 位置 |
|---|---|
| 文章 | notes/java/article.md |
| 图片 | notes/assets/demo.png |
问题:从文章出发,常见本地相对路径是什么?
参考答案:

解释:先用 ../ 从 java 返回 notes,再进入 assets。发布到博客时,还要确认系统是否按相同关系提供资源。
练习七:修好一张表格
有问题的内容:
| 语言 | 文件扩展名 |
| Java | .java |
| C | .c |
参考答案:
| 语言 | 文件扩展名 |
| --- | --- |
| Java | `.java` |
| C | `.c` |
检查:表头下面是否补上了分隔行?
练习八:让星号按原样显示
要求:在普通正文中显示 *重点*,不要让它变成斜体。
参考答案一,使用转义:
\*重点\*
参考答案二,作为语法示例显示:
`*重点*`
两种方法的排版外观不同,后者会使用行内代码样式。
练习九:判断是语法问题还是平台问题
现象:标题和列表都正常,但是 $$...$$、Mermaid 和 [TOC] 都直接显示为文字。
参考判断:先检查平台是否支持对应扩展,以及这些内容是否意外位于代码块中。不能仅凭显示为文字,就断定你的数学公式或流程图一定写错了。
练习十:写一篇自己的短文
题目任选一个:
- 我今天学会的三个 Vim 命令。
- Java 数组为什么从下标 0 开始。
- 我如何整理学习笔记。
要求:
- 一个一级标题。
- 至少三个二级标题。
- 至少两个正文段落。
- 一个有序列表或无序列表。
- 一处粗体和两处行内代码。
- 一个代码块。
- 一个有效链接。
- 在预览中检查全部效果。
完成后,再选择增加表格或图片。第一次练习不要求把所有扩展功能都用上。
30. 常用语法速查
30.1 基础写法
| 目的 | 原始写法 | 提醒 |
|---|---|---|
| 一级标题 | # 标题 |
井号后空一格 |
| 二级标题 | ## 标题 |
通常用于主要小节 |
| 三级标题 | ### 标题 |
通常用于小节内部 |
| 新段落 | 两段文字之间空一行 | 普通回车不一定产生新段落 |
| 粗体 | **重点** |
两端各两个星号 |
| 斜体 | *强调* |
两端各一个星号 |
| 无序列表 | - 项目 |
短横线后空一格 |
| 有序列表 | 1. 步骤 |
英文句点后空一格 |
| 引用 | > 内容 |
通常用来放摘录或补充说明 |
| 行内代码 | `变量名` |
使用反引号 |
| 链接 | [名称](地址) |
方括号加圆括号 |
| 图片 |  |
比链接多一个感叹号 |
| 分隔线 | --- |
单独一行,前后空行 |
| 转义星号 | \* |
反斜杠用于阻止特殊含义 |
30.2 常见扩展
| 目的 | 原始写法 | 兼容性提醒 |
|---|---|---|
| 删除线 | ~~旧内容~~ |
需要支持删除线扩展 |
| 未完成任务 | - [ ] 任务 |
需要支持任务列表 |
| 已完成任务 | - [x] 任务 |
不保证可在预览中点击修改 |
| 脚注引用 | [^note] |
还需要对应的脚注定义 |
| 行内公式 | $x^2$ |
需要公式渲染支持 |
| 独立公式 | 使用两组 $$ 包围公式 |
建议边界各占一行 |
| 自动目录 | 可能使用 [TOC] |
没有统一的通用写法 |
| 高亮 | 某些平台使用 ==文字== |
不是通用基础语法 |
30.3 三个值得直接收藏的结构
代码块:
```java
int count = 3;
```
表格:
| 名称 | 说明 |
| --- | --- |
| 第一项 | 第一项的说明 |
| 第二项 | 第二项的说明 |
图片加图注:

图 1:这张图片帮助说明的关键内容。
30.4 第一次写文章,先掌握这八项
- 用
#、##、###区分标题层级。 - 用空行区分段落。
- 用
**文字**强调重点。 - 用
-或1.整理列表。 - 用反引号包围命令、文件名和变量。
- 用配对的三个反引号展示多行代码。
- 用
[文字](地址)添加链接。 - 用
引用真实存在的图片。
接下来就可以用这些语法写一篇实际的学习笔记,再按需要逐步加入表格、公式和其他功能。
31. 官方资料与适用范围
以下资料用于进一步核对语法和平台行为。教程中的练习、文章内容与示例数据为原创教学内容;文件路径多为示例,实际使用时应替换成你的文件位置。
| 资料 | 适合查询什么 |
|---|---|
| CommonMark 0.31.2 规范 | 标题、段落、列表、强调、代码、链接、图片和换行的解析规则 |
| GFM 规范 | GitHub 风格的表格、任务列表和删除线等扩展 |
| GitHub 基本文字与格式语法 | GitHub 上的写作功能,包括脚注与提示框 |
| VS Code 的 Markdown 官方文档 | Markdown 预览、快捷键及编辑功能 |
| GitHub 数学表达式文档 | GitHub 支持的数学公式写法 |
| Mermaid 流程图文档 | 流程图节点、连接和判断分支 |
| Hugo Front Matter 文档 | Hugo 文章元数据与草稿等字段 |
资料核对日期:2026 年 9 月 23 日。软件版本、站点主题和启用的扩展可能不同;遇到差异时,以实际发布平台的文档和预览结果为准。