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 创建

  1. 新建文本文件。
  2. 输入几行内容。
  3. 保存,文件名填写 markdown-practice.md。
  4. 确认编辑器把文件识别为 Markdown。
  5. 打开 Markdown 预览,对照源文字查看效果。

具体预览快捷键在第 23 节。

2.3 用 Vim 创建

下面这一行应当在终端中执行:

vim markdown-practice.md

进入 Vim 后:

  1. 按小写 i,进入插入模式。
  2. 输入或粘贴文章。
  3. 按 Esc,回到普通模式。
  4. 输入 :w 并按回车,保存。
  5. 输入 :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. 打开预览并检查。

显示效果:

  1. 创建 Markdown 文件。
  2. 输入文章内容。
  3. 保存文件。
  4. 打开预览并检查。

数字后面使用英文句点 .,句点后面留一个空格。

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!");
    }
}

逐行理解:

  1. 开头的三个反引号表示“代码块开始”。
  2. java 是语言标识,用于提示支持高亮的平台按 Java 着色。
  3. 中间放代码。
  4. 结尾的三个反引号表示“代码块结束”。

开始围栏和结束围栏通常各自独占一行。初学时让它们从行首开始写,列表内部则按照列表要求整体缩进。

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/)

显示效果:

查看 Markdown 规范

结构是:

[读者看到的文字](实际跳转地址)

方括号中是名称,圆括号中是地址。两部分之间不要插入额外空格。

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)

![数组元素与下标的对应关系](./images/array-example.png)

第一行创建指向图片的链接;第二行请求直接显示图片。

本节的图片路径用于教学。只有对应图片文件真实存在,预览器才能显示它。

14.2 方括号中的文字是什么

方括号中是替代文字,通常称为 alt 文本。它可以帮助使用屏幕阅读器的人理解图片,也可能在图片加载失败时显示。

推荐描述图片包含的信息:

![长度为 3 的数组,下标从 0 到 2](./images/array-example.png)

比下面的写法更有用:

![图片](./images/array-example.png)

替代文字通常不会自动成为图片下方的可见图注。需要图注时,在图片后空一行,另外写一段说明。

14.3 本地图片路径怎么找

假设文件布局如下:

文件路径 用途
notes/article.md 当前文章
notes/images/array-example.png 配套图片
notes/images/result.png 配套图片

在 article.md 中,常见本地预览写法是:

![数组示意图](./images/array-example.png)

读取方式是:从当前文章所在目录出发,进入 images 目录,寻找 array-example.png。

14.4 图片位于上一级目录时

另一种布局:

文件路径 用途
notes/java/article.md 当前文章
notes/images/array-example.png 配套图片

此时文章中的相对路径可以写成:

![数组示意图](../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 图片不显示,按这个顺序排查

  1. 目标图片文件是否真的存在?
  2. 文件名是否拼错?
  3. .png、.jpg、.jpeg 等扩展名是否一致?
  4. 大小写是否完全一致,例如 Photo.png 与 photo.png?
  5. 相对路径是否从正确位置出发?
  6. 发布时图片是否一起上传?
  7. 网络图片地址是否需要登录、已失效或限制外部访问?

建议路径使用 /,并且严格保持大小写一致。某些本地环境对大小写较宽松,部署环境可能严格区分。

14.8 如何设置宽度或图注

基础 Markdown 没有统一的图片宽度、居中和图注语法。

图注可以先这样写:

![数组示意图](./images/array-example.png)

图 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 三个部分分别做什么

  1. 第一行是表头。
  2. 第二行是分隔行,告诉解析器“这是一个表格”。
  3. 后面的行是数据。

竖线 | 分隔不同列。表头和分隔行的列数需要一致;为了避免丢失内容,每条数据也按相同列数填写。

分隔行每列统一使用至少三个短横线,是便于阅读、兼容常见工具的写法。

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 更稳妥的做法

  1. 先在目标平台显示文章。
  2. 找到目标标题旁边的链接图标,或平台提供的标题链接。
  3. 复制实际生成的锚点。
  4. 放入目录链接中。
  5. 点击验证是否跳转到正确位置。

如果修改了标题,也要检查原有的页内链接是否仍然有效。

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 公式不显示时

依次检查:

  1. 目标平台是否支持公式,是否需要打开设置?
  2. 美元符号是否配对?
  3. 是否误把公式放进了普通代码块?
  4. 反斜杠、花括号或环境名称是否写错?
  5. 当前数学渲染工具是否支持所用命令?

教程把公式源文字放在代码框中,是为了让你看清写法。实际希望显示公式时,要把代码框里面的 $ 或 $$ 写入正文,不要连同最外面的示例代码围栏一起保留。

参考: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 主要负责编辑源文字。语法高亮可以帮助识别标记,但它本身不等同于网页式预览。

简单做法是:

  1. 在 Vim 中编辑文章。
  2. 按 Esc,输入 :w 并回车,保存。
  3. 用支持 Markdown 预览的软件打开同一份文件,或查看博客预览页面。
  4. 修改后再次保存,确认预览更新。

不要同时在两个编辑器里修改同一个文件却不保存,避免混淆哪一份修改才是最新的。

如果文件在服务器上,要确认预览软件打开的确实是那份远程文件,或者是刚刚同步的副本。

23.4 双击 .md 不一定直接看到排版效果

双击文件后打开哪个软件,由系统文件关联决定。它可能打开记事本、Vim、VS Code,也可能打开专门的阅读器。

看到 # 和反引号,通常说明当前是源文字编辑界面。需要寻找“预览”入口,而不是马上认为文件坏了。

23.5 本地预览正确后,还要检查目标网站

本地预览主要确认正文语法。网站预览还能确认:

  • 主题是否重复显示文章标题。
  • 图片最终地址是否正确。
  • 表格是否太宽,手机上是否易读。
  • 数学公式、流程图等功能是否启用。
  • 文章目录和页内链接是否正常。

预览与发布是不同步骤。保存一个 .md 文件,不一定自动更新互联网上的文章。

24. 一次完整的 Markdown 写作流程

第一步:确定这篇文章解决什么问题

先用一句话写清楚目标,例如:

这篇文章说明 Java 数组如何声明、访问和遍历。

如果一句话中塞进了太多主题,先缩小范围。一个小问题讲清楚,比多个大主题各写两句更有用。

第二步:创建文件并拟好名称

例如 java-array-notes.md。先保存文件,确认位置和扩展名。

如果你在既有博客项目里写作,使用项目已有的文章创建流程,保留它生成的 Front Matter 和目录约定。

第三步:只写标题骨架

# Java 数组学习笔记

## 1. 数组是什么

## 2. 如何创建数组

## 3. 如何访问元素

## 4. 如何遍历数组

## 5. 常见错误

此时先检查逻辑顺序,暂时不用处理字体和图片大小。

第四步:在每个标题下填普通文字

一段集中解释一个意思。如果内容是并列项目,改成列表;如果内容是先后步骤,改成有序列表。

不要把整篇文章写成一连串没有解释的代码块。代码上下应说明它解决什么问题、读者应关注什么。

第五步:加入示例和结果

技术笔记可以采用:

  1. 先解释目的。
  2. 给出可以复制的代码或命令。
  3. 展示必要的输出。
  4. 说明输出为什么是这样。
  5. 提醒与当前问题直接相关的常见错误。

示例应尽量短,能够单独说明一个知识点。

第六步:补充链接和图片

优先加入真正帮助理解的材料。图片出现后,用一两句话说明读者应该看哪里;链接文字说明它的用途。

如果引用了本地图片,确认图片也保存在文章配套目录或博客要求的资源目录中。

第七步:保存并检查预览

先查看结构,再检查细节:

  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

问题:从文章出发,常见本地相对路径是什么?

参考答案:

![示例图片](../assets/demo.png)

解释:先用 ../ 从 java 返回 notes,再进入 assets。发布到博客时,还要确认系统是否按相同关系提供资源。

练习七:修好一张表格

有问题的内容:

| 语言 | 文件扩展名 |
| Java | .java |
| C | .c |

参考答案:

| 语言 | 文件扩展名 |
| --- | --- |
| Java | `.java` |
| C | `.c` |

检查:表头下面是否补上了分隔行?

练习八:让星号按原样显示

要求:在普通正文中显示 *重点*,不要让它变成斜体。

参考答案一,使用转义:

\*重点\*

参考答案二,作为语法示例显示:

`*重点*`

两种方法的排版外观不同,后者会使用行内代码样式。

练习九:判断是语法问题还是平台问题

现象:标题和列表都正常,但是 $$...$$、Mermaid 和 [TOC] 都直接显示为文字。

参考判断:先检查平台是否支持对应扩展,以及这些内容是否意外位于代码块中。不能仅凭显示为文字,就断定你的数学公式或流程图一定写错了。

练习十:写一篇自己的短文

题目任选一个:

  • 我今天学会的三个 Vim 命令。
  • Java 数组为什么从下标 0 开始。
  • 我如何整理学习笔记。

要求:

  1. 一个一级标题。
  2. 至少三个二级标题。
  3. 至少两个正文段落。
  4. 一个有序列表或无序列表。
  5. 一处粗体和两处行内代码。
  6. 一个代码块。
  7. 一个有效链接。
  8. 在预览中检查全部效果。

完成后,再选择增加表格或图片。第一次练习不要求把所有扩展功能都用上。

30. 常用语法速查

30.1 基础写法

目的 原始写法 提醒
一级标题 # 标题 井号后空一格
二级标题 ## 标题 通常用于主要小节
三级标题 ### 标题 通常用于小节内部
新段落 两段文字之间空一行 普通回车不一定产生新段落
粗体 **重点** 两端各两个星号
斜体 *强调* 两端各一个星号
无序列表 - 项目 短横线后空一格
有序列表 1. 步骤 英文句点后空一格
引用 > 内容 通常用来放摘录或补充说明
行内代码 `变量名` 使用反引号
链接 [名称](地址) 方括号加圆括号
图片 ![说明](图片地址) 比链接多一个感叹号
分隔线 --- 单独一行,前后空行
转义星号 \* 反斜杠用于阻止特殊含义

30.2 常见扩展

目的 原始写法 兼容性提醒
删除线 ~~旧内容~~ 需要支持删除线扩展
未完成任务 - [ ] 任务 需要支持任务列表
已完成任务 - [x] 任务 不保证可在预览中点击修改
脚注引用 [^note] 还需要对应的脚注定义
行内公式 $x^2$ 需要公式渲染支持
独立公式 使用两组 $$ 包围公式 建议边界各占一行
自动目录 可能使用 [TOC] 没有统一的通用写法
高亮 某些平台使用 ==文字== 不是通用基础语法

30.3 三个值得直接收藏的结构

代码块:

```java
int count = 3;
```

表格:

| 名称 | 说明 |
| --- | --- |
| 第一项 | 第一项的说明 |
| 第二项 | 第二项的说明 |

图片加图注:

![准确描述图片内容](./images/demo.png)

图 1:这张图片帮助说明的关键内容。

30.4 第一次写文章,先掌握这八项

  1. 用 #、##、### 区分标题层级。
  2. 用空行区分段落。
  3. 用 **文字** 强调重点。
  4. 用 - 或 1. 整理列表。
  5. 用反引号包围命令、文件名和变量。
  6. 用配对的三个反引号展示多行代码。
  7. 用 [文字](地址) 添加链接。
  8. 用 ![说明](地址) 引用真实存在的图片。

接下来就可以用这些语法写一篇实际的学习笔记,再按需要逐步加入表格、公式和其他功能。

31. 官方资料与适用范围

以下资料用于进一步核对语法和平台行为。教程中的练习、文章内容与示例数据为原创教学内容;文件路径多为示例,实际使用时应替换成你的文件位置。

资料 适合查询什么
CommonMark 0.31.2 规范 标题、段落、列表、强调、代码、链接、图片和换行的解析规则
GFM 规范 GitHub 风格的表格、任务列表和删除线等扩展
GitHub 基本文字与格式语法 GitHub 上的写作功能,包括脚注与提示框
VS Code 的 Markdown 官方文档 Markdown 预览、快捷键及编辑功能
GitHub 数学表达式文档 GitHub 支持的数学公式写法
Mermaid 流程图文档 流程图节点、连接和判断分支
Hugo Front Matter 文档 Hugo 文章元数据与草稿等字段

资料核对日期:2026 年 9 月 23 日。软件版本、站点主题和启用的扩展可能不同;遇到差异时,以实际发布平台的文档和预览结果为准。