当前位置： 首页 > article >正文

Markdown 语法入门指南（VSCode 版）

article 2025/3/14 3:12:11

此博客为一份详细的 Markdown 语法入门指南，专门针对在 VSCode 上使用 Markdown 的零基础用户。这份指南将包括 Markdown 的基础语法、在 VSCode 中的安装与使用方式、常见问题及注意事项。

Markdown 是一种轻量级标记语言，使用纯文本符号来标记格式，使文档既易读又易写。它常用于编写技术文档、博客文章、GitHub 项目README等，在各类平台上广泛流行 (Markdown 教程 | 菜鸟教程)。本指南将按照提纲，帮助零基础用户快速上手 Markdown，并结合 VSCode 编辑器介绍其用法和技巧。

1. 什么是 Markdown？

Markdown 由约翰·格鲁伯（John Gruber）于 2004 年创建，是一种旨在让人们用纯文本格式编写文档的语言 (Markdown 教程 | 菜鸟教程)。它使用直观的符号（如#、*等）来表示标题、列表等格式，以确保可读性：Markdown 文件可以直接以纯文本形式阅读，不显得杂乱，同时也能转换为 HTML 等格式用于展示。

Markdown 的优势和用途主要包括：

  • 用途广泛：适用于撰写各种内容，如技术文档、笔记、博客文章、电子书等。许多网站和工具（如 GitHub、GitBook、简书等）都支持 Markdown 来书写说明文档或帖子 (Markdown 教程 | 菜鸟教程)。
  • 简洁高效：相比富文本编辑器，Markdown 语法简单明了，格式操作主要依靠键盘输入符号，极大提高书写效率。
  • 易于转换：Markdown 文档可以轻松转换为 HTML、PDF、Word 等多种格式进行发布和分享。由于 Markdown 文件本质是文本，和版本控制系统（如 Git）配合也非常友好，方便追踪更改历史。

总之，Markdown 让创作者专注于内容本身，而无需过多关心排版细节，是编写各类文档的理想选择。

2. 在 VSCode 上使用 Markdown

Visual Studio Code (VSCode) 对 Markdown 有开箱即用的支持。只需在 VSCode 中打开或新建一个扩展名为.md的文件，即可开始编写 Markdown。VSCode 默认内置了 Markdown 语法高亮和基本预览功能 (Markdown 教程 | 菜鸟教程)。

为了更好地在 VSCode 中编辑和预览 Markdown，推荐安装以下扩展插件：

  • Markdown All in One：提供一系列实用功能（如键盘快捷键、目录生成、自动预览、图像粘贴上传等）来增强 Markdown 编辑体验 (VSCode 中优雅地编写 Markdown - zhangyi1357 - 博客园)。安装后可以使用插件的快捷键快速插入格式，生成目录等，提高效率。
  • Markdown Preview Enhanced：功能强大的 Markdown 增强插件，支持数学公式、Mermaid 流程图、PlantUML 绘图、PDF 导出等高级特性 ( Markdown Preview Enhanced - Visual Studio Marketplace ) (在 VSCode 下用 Markdown Preview Enhanced 愉快地写文档-CSDN博客)。它为 VSCode 提供了一个更丰富的预览窗口，方便实时查看复杂内容的渲染效果。

安装上述插件后，VSCode 将更加得心应手地编辑 Markdown。另外，还可根据需要安装 MarkdownLint（语法风格检查）、Markdown PDF（将文档导出为 PDF）等插件，这里不再详述。

在 VSCode 中预览 Markdown 文档：VSCode 自带 Markdown 文件预览功能。打开一个 .md 文件后，可以通过以下方式调出预览：

  • 使用快捷键 Ctrl+Shift+V（Mac 上为 Cmd+Shift+V）可以直接在编辑器中打开Markdown预览 (在VSCode中高效编辑markdown的正确方式 – 就是这个范儿)。
  • 使用快捷键 Ctrl+K V（先按 Ctrl+K 松开，再按 V）可以在编辑窗口旁边侧边预览，实现一边编辑一边预览 (在VSCode中高效编辑markdown的正确方式 – 就是这个范儿)。
  • 也可以通过命令面板（Ctrl+Shift+P）运行命令：Markdown: Open Preview 或 Markdown: Open Preview to the Side 来打开预览窗口。右上角的双窗口图标按钮也能切换编辑/预览视图。

预览窗口会实时渲染 Markdown 内容，方便查看排版效果。使用插件 Markdown All in One 时，还可以在设置中启用“保存时自动预览”等功能，实现更加实时的预览体验。

3. Markdown 基本语法

下面介绍 Markdown 的基本语法，包括标题、段落、文本格式等常用元素。每种语法会附带示例，帮助你了解Markdown 源码和预览效果之间的对应关系。

标题（Headers）

Markdown 使用 # 符号表示标题级别。# 的个数对应标题级别：

  • # 标题1 表示一级标题（通常文档标题）。
  • ## 标题2 表示二级标题（章节标题）。
  • 以此类推，最多支持六级标题（###### 标题6）。

示例：

# 这是一级标题
## 这是二级标题
### 这是三级标题

在预览中，一级标题通常字体最大、加粗显示；二级标题次之，以此递减。注意在 # 和标题文字之间需要有空格。此外，尽量按顺序使用标题级别，不要跳级使用，以保证文档结构清晰。

段落和换行（Paragraphs & Line Breaks）

普通文本直接书写就是一个段落。段落之间要空一行，否则会被连成同一段。要在段落内强制换行（即不新起一段），有以下方法：

  • 在行尾加两个及以上空格然后换行，可以插入一个换行（）。
  • 使用显式的换行标签 <br> 插入换行。

例如，在以下Markdown源码中第二句末尾有两个空格，将产生换行：

这是第一行文本。  
这是第二行文本（同段落换行）。

预览效果会将两行分别显示但仍属于同一段落。若省略两个空格，上例两行将在预览中合并成一行连续文本。

文本格式（Bold, Italic, Strikethrough）

Markdown 提供基本的文字样式，通过符号包围文本实现：

  • 粗体：使用双星号 **粗体文本**（或双下划线 __粗体文本__）来加粗文字。
  • 斜体：使用单星号 *斜体文本*（或单下划线 _斜体文本_）来倾斜文字。
  • 删除线：使用双波浪线 ~~删除线文本~~ 来表示删除或划掉的文字。

示例：

这是**加粗**的文字，这是*斜体*，这是~~删除线~~。

预览中，加粗文本通常以粗体显示，斜体文本以斜体显示，删除线文本会被中间划一条横线。在需要强调或表明修改的场景下，这些格式非常有用。

引用块（Blockquote）

使用 > 引导的段落会被渲染为引用块。引用块通常用于引用他人的文章、提示信息等。可以在 > 后直接书写内容。引用块也可以嵌套：在已有 > 的段落前再添加一个 >，就形成嵌套引用。

示例：

> 这是一个引用段落，用于引用他人的文字或强调重点。
> 
> 引用可以包含多个段落。在每个段落前都加上`>`。
>> 嵌套引用：在一个引用内再引用。

预览效果：引用块通常有缩进和左侧的竖线样式。嵌套引用会进一步缩进。通过引用块，可以将引用内容与正文区分开。

代码块与行内代码（Code Blocks & Inline Code）

Markdown 使用反引号 (`) 来表示代码。

  • 行内代码：用单个反引号把代码围起来，例如 `printf("Hello");`。行内代码会在预览中以等宽字体显示，背景略有高亮，适合短代码或命令的引用。
  • 代码块：使用三个反引号开头和结尾来创建多行代码块。你可以在开头的反引号后指定代码语言（例如 "```python"），以启用语法高亮。

示例（行内代码和代码块）：

在 C 语言中，你可以调用 `printf("Hello");` 来打印输出。

```c
#include <stdio.h>
int main() {
    printf("Hello, Markdown!\n");
    return 0;
}


在以上示例中，第一行的 *printf("Hello");* 被渲染为行内代码。随后是一段 C 代码块（用 ```c 标记），在预览中会按C语言语法进行高亮显示。使用代码块可以方便地展示代码片段、终端输出等内容，而不会被Markdown解释为格式标记。

### 列表（Lists）

Markdown 支持**无序列表**和**有序列表**：

- **无序列表**：使用 `-`、`*` 或 `+` 加空格作为列表项开头。多个列表项将形成一个无序列表。  
- **有序列表**：使用数字后紧跟一个英文句点和空格（如 `1. `、`2. `）作为列表项开头。数字的实际值一般不影响输出（所有项用`1.`也会自动编号），但为了清晰通常按照顺序编号。

示例：

```markdown
无序列表示例：
- 项目 A
- 项目 B
  - 子项目 B1  （缩进两个空格形成子列表）
  - 子项目 B2

有序列表示例：
1. 步骤一
2. 步骤二
3. 步骤三

预览中，无序列表项通常以圆点或小符号显示；有序列表则按顺序编号。注意为了正确形成列表，列表项标记后需接空格，与上一段落之间要有空行分隔。子列表通过在标记前缩进（一般两个或四个空格）来创建。

表格（Tables）

Markdown 可以创建简单的表格。使用管道符号 | 分隔不同的列，使用短横线 - 构成表头下的分隔线。语法如下：

| 商品   | 价格   | 数量 |
| ------ | ------ | ---- |
| 苹果   | 5 元   | 3    |
| 香蕉   | 2 元   | 5    |

说明：第一行定义表头各列，第二行使用 --- 表示表头与表格主体的分隔（至少三个短横线，可在两侧加:来控制列内容对齐方式：居左:-, 居中:-:, 居右-:），后续行每行一条记录。以上示例将生成一个三列的表格，包含两行数据。

在预览中，表格会以网格形式显示，首行通常加粗作为表头。确保每行的管道数量一致，否则可能无法正确渲染表格。此外，Markdown 原生表格不支持复杂的单元格合并等功能，仅适用于简单数据展示。

链接与图片（Links & Images）

编写超链接和插入图片是 Markdown 的重要功能：

  • 链接：使用 [链接文本](URL) 的格式创建。点击预览中的链接文本会打开对应的 URL。例如：[访问百度](https://www.baidu.com) 会显示为一个可点击的“访问百度”超链接。
  • 图片：语法与链接类似，但在最前面加一个感叹号 !。格式为：![替代文本](图片URL)。替代文本会在图片无法加载时显示，也用于屏幕阅读器。示例：![Markdown 标志](https://markdown-here.com/img/icon256.png) 会插入一张来自网络的 Markdown 标志图片。

请注意，若使用本地图片，可以使用相对路径或绝对路径，例如：![本地图片](./images/pic01.png)。在 VSCode 的 Markdown 预览中，本地图片路径是相对于当前 Markdown 文件的位置的，需要确保路径正确。若图片无法显示，可能需要检查路径或启用不安全内容（VSCode 默认 Markdown 预览出于安全限制，不加载本地磁盘以外的资源，可通过命令面板搜索“Markdown: Change Preview Security Settings”调整设置以允许本地文件）。

分割线（Horizontal Rule）

分割线可用于分隔内容、强调主题转换。在 Markdown 中，任意一行包含三个或以上的连续符号如 ***、--- 或 ___ （星号、短横线、下划线）都将渲染为一条水平分割线。

示例：

内容段落1

---

内容段落2

上述 --- 将被转换为一条水平直线，将段落1与段落2分隔开。分割线前后需各空一行。常用的分割线写法是三个短横线，如上例所示。

任务列表（Task List）

任务列表是 Markdown 的扩展语法（在 GitHub Flavored Markdown 等平台支持）。在无序列表的基础上，通过在列表项前加 [ ] 或 [x] 来表示复选框（未选中或选中状态），可以创建待办事项列表。

示例：

待办事项：
- [x] 完成 Markdown 基础语法学习
- [ ] 安装 VSCode 的 Markdown 插件
- [ ] 用 Markdown 撰写一篇笔记

在预览中，上述列表会显示为带复选框的任务清单，其中已完成的第一项显示为勾选状态。这个功能常用于编写计划、任务清单等。要注意在方括号与列表文本之间留有一个空格。VSCode 的内置预览支持任务列表渲染（它遵循 GitHub 风格 Markdown），但纯文本查看时你仍然会看到原始的[x]标记。

4. 高级 Markdown 语法

除了上述基本语法，Markdown 还可以通过一些扩展实现更高级的排版需求。在 VSCode 中，借助插件和一些技巧，可以使用图表、公式以及自定义样式等高级功能。

Mermaid 图表和数学公式

在文档中插入流程图、序列图等图表以及数学公式，可以使用 VSCode 插件 Markdown Preview Enhanced (MPE) 实现。MPE 插件支持直接使用 Mermaid 语法绘制图表，以及使用 LaTeX 语法插入数学公式 (在 VSCode 下用 Markdown Preview Enhanced 愉快地写文档-CSDN博客)。

  • Mermaid 图表：Mermaid 是一种用文本描述图表的工具。通过编写 mermaid 代码块，在其中写入图表定义，Markdown 预览将渲染出相应的图形。例如，在 Markdown 中输入：
```mermaid
graph LR
    A[开始] --> B[过程] --> C[结束]
```

以上代码将绘制一个从“开始”到“过程”再到“结束”的流程图（LR表示从左到右）。你可以用类似的方法画流程图、甘特图、时序图等多种图表。需要确保已安装并启用了 MPE 插件，否则普通 Markdown 不会识别 mermaid 代码块。

  • 数学公式：使用数学公式时，一般采用 LaTeX 语法。MPE 插件允许我们在 Markdown 中通过 $$ ... $$ 包围块级公式，通过 $ ... $ 包围行内公式，然后在预览中渲染为数学符号。例如：
这是行内公式 $E=mc^2$ 示例。

$$
E = mc^2
$$

上述行内公式将在文本中显示为 $E=mc^2$，而独立居中的块级公式会显示为\(E = mc^2\)。你可以编写更复杂的公式，比如矩阵、积分符号等，MPE 将调用数学排版引擎（如 KaTeX）进行渲染，使其显示为标准的数学格式。

提示：Mermaid 图表和数学公式都是 Markdown 的扩展功能，需要预览工具的支持。VSCode 官方内置预览并不直接支持它们，但通过安装 MPE 插件即可。使用这些功能时，建议先在 VSCode 中确认预览效果是否符合预期，如果不生效请检查插件是否正确安装并启用。

使用 HTML 语法扩展 Markdown

Markdown 本质上会被转换为 HTML 来显示。因此，你可以在 Markdown 文档中直接编写HTML 标签来实现一些 Markdown 无法覆盖的布局或格式。

例如：

  • 如果想插入视频或更复杂的内容，可以直接粘贴相应的 <video>、<iframe> 等 HTML 标签。
  • 如果需要控制某段文字的颜色或大小（Markdown 无直接语法），可以使用内联的 <span style="...">...</span> 或 <font> 标签（不推荐，已过时）来调整样式。
  • 可以通过 HTML 实现更复杂的表格布局，或者定义折叠面板、按钮等交互元素（前提是目标输出环境支持这些 HTML）。

需要注意的是，并非所有 Markdown 渲染环境都会完全信任并执行HTML。例如 GitHub的README会屏蔽某些HTML标签出于安全考虑。但在 VSCode 本地预览中，大部分简单 HTML 标签都会按预期渲染。另外，为了保持 Markdown 文档的可读性，只有在确有必要时才掺入 HTML，并且尽量在块级元素（如段落之间）使用，以免破坏 Markdown 原有结构。

自定义 CSS 样式美化 Markdown

VSCode 的 Markdown 预览支持通过自定义 CSS 来调整样式。如果你对默认的预览样式不满意（例如想更改背景颜色、字体、代码块主题等），可以使用以下方法进行美化：

  • 更改预览主题：一些插件（如 MPE）内置了多种主题样式，可在其设置中选择。例如 MPE 提供了 GitHub 风格、黑色主题等预览主题，直接修改插件设置 markdown-preview-enhanced.previewTheme 即可应用不同的配色 (VSCode 中优雅地编写 Markdown - zhangyi1357 - 博客园)。
  • 加载自定义 CSS：VSCode 内置预览允许在设置中指定自定义CSS文件。步骤为：新建一个 CSS 文件，编写你希望覆盖的样式规则（例如修改 h1, h2 标题颜色，调整表格样式等）；然后在 VSCode 设置中搜索 “Markdown > Styles”，将刚才CSS文件的路径添加进去 (VSCode 自定义Markdown 预览样式 - 码志)。再次打开 Markdown 预览时，就会应用你的定制样式。这样你可以彻底掌控预览的外观，使之符合你的审美或阅读习惯。

通过自定义 CSS，你甚至可以使 VSCode 的 Markdown 预览风格与特定的网站风格一致（比如 GitHub 风格），或者实现夜间深色模式预览等。但请注意，此操作仅影响本地预览，对实际导出的HTML或其他平台上的显示无直接影响（除非那些平台也引用了你的CSS）。

5. VSCode Markdown 常见问题及解决方案

在使用 VSCode 编辑 Markdown 时，可能会遇到一些常见问题。以下列出几个问题及对应的解决方法：

  • 预览无法打开：当按下快捷键或命令后，Markdown 预览没有出现时，首先确认文件已保存且扩展名为 .md。然后确保 VSCode 的 Markdown 预览功能正常启用（可尝试通过菜单 “打开预览” 来验证）。如果安装了第三方 Markdown 插件，某些插件设置可能影响内置预览，尝试禁用冲突的插件。最后，检查命令是否正确，例如应使用 Markdown: Open Preview to the Side 而非其它相似命令。

  • 图片无法显示：预览中图片不显示通常有两种情况：其一，图片路径错误或图片文件不存在。请检查 Markdown 中引用的路径是否有效（相对路径要相对于当前 Markdown 文件）。其二，VSCode 出于安全设置阻止加载本地或非安全链接图片。如果确定路径无误却仍不显示，可在命令面板运行 “Markdown: Change Preview Security Settings”（更改预览安全设置），选择放宽安全限制（例如允许本地文件或不安全内容），然后重新加载预览 (VSCode开启侧边预览，MarkDown文件中图片无法显示 - 稀土掘金)。一般来说，本地图片确保路径正确即可显示，网络图片则要求有稳定的外链地址。

  • 代码高亮失效：代码块未呈现出应有的高亮可能有几种原因。首先，确认你在三反引号后正确标注了语言（例如 java、python 等）；如果未标注语言，预览可能默认不高亮或只能做基本高亮。其次，可能是 VSCode 使用的主题对代码块配色不明显，你可以切换 VSCode 主题或 Markdown 预览主题来查看效果。另外，若使用了 Markdown 扩展插件，检查其设置中是否关闭了代码高亮功能。一般VSCode内置预览使用 markdown-it 引擎遵循 CommonMark 标准并支持大部分语言的高亮，如发现某种语言不高亮，可以考虑安装相应语言的 VSCode 扩展以提供语法支持。

  • 表格格式问题：有时 Markdown 表格在预览中未正确显示，常见原因是表格语法不规范。确保表格有正确的管道符和分隔线——尤其是第二行的 --- 分隔符，每列至少三个短横线，且管道符数量匹配。表格前后需要空行分隔，否则可能被识别成上一段内容的一部分。此外，如果表格内容较长，换行处可能需要在单元格内使用 <br> 实现。VSCode 的 Markdown All in One 插件提供了表格格式化功能，输入表格后按下 Alt+Shift+F 可以自动对齐列方便阅读，不过这不影响预览渲染，只是美观问题。

6. Markdown 实战示例

介绍了这么多，现在通过一个完整的 Markdown 示例来串联所学的语法。下面是一份包含各种 Markdown 语法元素的示例文档，你可以将其复制到 VSCode 中并打开预览查看效果：

# 我的笔记标题

Hello，这是一个**Markdown 示例文档**，展示常用的 Markdown 语法。

## 一些文本格式

你可以使用 *斜体*、**粗体** 和 ~~删除线~~ 来突出文字的不同语气。  
Markdown 段落默认连续书写会合并在一起，上面这行末尾有两个空格，  
所以它在预览中会换行而不产生新段落。

还可以使用引用来强调重要内容：

> 学习 Markdown **非常简单**，熟练掌握后可以大大提升写作效率！

## 列表与代码

无序列表示例：
- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2

有序列表示例：
1. 第一步骤
2. 第二步骤
3. 第三步骤

行内代码示例：在命令行中输入 `npm install` 安装依赖。  

代码块示例（下面是一段Python代码）：

```python
def greet(name):
    print(f"你好, {name}!")

greet("Markdown")

表格与任务列表

下面是一个表格示例：

品项数量价格
苹果 🍎4¥20
香蕉 🍌6¥18

任务列表示例：

  • 已完成事项
  • 待办事项1
  • 待办事项2

链接与图片

这是一个链接示例：访问 VSCode 官网.

下面插入一张图片示例（Markdown 标志）：

Markdown 标志

（本示例涵盖了 Markdown 基础语法，你可以尝试修改并观察预览效果。）


将上述内容粘贴到 VSCode 的 Markdown 文件中并切换到预览，可以看到各种元素（标题、文本格式、列表、代码、高亮、表格、复选框、链接、图片等）是如何渲染的。通过实践，你会对哪些符号产生哪些效果有更直观的认识。

## 7. 参考资源

- **Markdown 官方文档（英文）** – [Daring Fireball: Markdown Syntax](https://daringfireball.net/projects/markdown/syntax)：Markdown 创始人提供的语法说明，详细定义了标准 Markdown 的各项语法规则。

- **Markdown 教程（中文）** – [菜鸟教程：Markdown 简明教程](https://www.runoob.com/markdown/md-tutorial.html)：面向入门者的中文教程，涵盖 Markdown 基础语法和一些进阶技巧，还有对应示例，非常适合初学查阅。

- **VSCode 插件：Markdown All in One** – [Marketplace 链接](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)：一站式的 Markdown 编辑辅助插件，提供快捷键、自动生成目录、格式化表格等多种实用功能，大幅提升在 VSCode 中写 Markdown 的效率。

- **VSCode 插件：Markdown Preview Enhanced** – [Marketplace 链接](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced)：功能强大的 Markdown 增强预览插件。支持数学公式、流程图、幻灯片导出等高级功能。如果你的文档有高级排版需求，推荐使用该插件来获得更好的预览效果和扩展能力。

希望本指南能帮助你顺利迈出 Markdown 学习的第一步。在 VSCode 中熟练使用 Markdown，能够让写作和记录变得简单而高效。祝你在今后的创作中玩转 Markdown！

http://www.kler.cn/a/580919.html

相关文章：

  • 记录一次openwebui部署无法使用知识库的问题
  • Ubuntu本地部署Open manus（完全免费可用）
  • 电商项目中如何选择安全高效的电商API接口？
  • Flutter 学习之旅 之 flutter 全屏背景图设置功能的简单实现
  • 每日一题----------String 和StringBuffer和StringBuiler重点
  • VSCode 2025最新前端开发必备插件推荐汇总（提效指南）
  • Python 编写第一个网络爬虫教程
  • 面向高质量视频生成的扩散模型方法-算法、架构与实现【附核心代码】
  • 【Java 面试 八股文】计算机网络篇
  • 解锁Android Framework：AOA通信全攻略
  • UI-APP---基于HBuilder X的微信小程序
  • Nuxt3 ssr build/dev时区分不同的环境
  • 内网激活JRebel插件(无网络环境)
  • Spring框架中的单例Bean是线程安全的吗
  • Windows Docker Desktop 设置中文
  • 【C++中的STL】
  • 【每日学点HarmonyOS Next知识】获取资源问题、软键盘弹起、swiper更新、C给图片设置位图、读取本地Json
  • IDEA软件安装环境配置中文插件
  • 面试之《技巧》
  • 在 IntelliJ IDEA 中使用 JUnit 进行单元测试