目录

Markdown-语法入门指南VSCode-版

Markdown 语法入门指南(VSCode 版)

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

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

1. 什么是 Markdown?

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

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

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

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

2. 在 VSCode 上使用 Markdown

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

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

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

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

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

  • 使用快捷键 Ctrl+Shift+V (Mac 上为 Cmd+Shift+V)可以直接在编辑器中打开Markdown预览 ( )。
  • 使用快捷键 Ctrl+K V (先按 Ctrl+K 松开,再按 V)可以在编辑窗口旁边 侧边预览 ,实现一边编辑一边预览 ( )。
  • 也可以通过 命令面板 (Ctrl+Shift+P)运行命令: Markdown: Open PreviewMarkdown: 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 原生表格不支持复杂的单元格合并等功能,仅适用于简单数据展示。

编写超链接和插入图片是 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 语法插入数学公式 ( )。

  • 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 - 博客园](https://www.cnblogs.com/zhangyi1357/p/17940788#:~:text= "VSCode 中优雅地编写 Markdown - zhangyi1357 - 博客园")
  )。
* **加载自定义 CSS**
  :VSCode 内置预览允许在设置中指定自定义CSS文件。步骤为:新建一个 CSS 文件,编写你希望覆盖的样式规则(例如修改
  `h1, h2`
  标题颜色,调整表格样式等);然后在 VSCode
  **设置**
  中搜索 “Markdown > Styles”,将刚才CSS文件的路径添加进去 (
  [VSCode 自定义Markdown 预览样式 - 码志](https://mazhuang.org/fragment/vscode-markdown-preview-custom-css/#:~:text=VSCode%20%E9%87%8C%E9%BB%98%E8%AE%A4%E7%9A%84Markdown%20%E9%A2%84%E8%A7%88%E6%A0%B7%E5%BC%8F%E4%B8%8D%E5%A4%AA%E5%A5%BD%E7%9C%8B%EF%BC%8C%E5%8F%AF%E4%BB%A5%E8%87%AA%E5%AE%9A%E4%B9%89%E6%A0%B7%E5%BC%8F%E3%80%82%20%E6%96%B9%E6%B3%95%E6%98%AF%E5%9C%A8VSCode%20%E7%9A%84%E9%85%8D%E7%BD%AE%E9%87%8C%EF%BC%8C%E6%89%BE%E5%88%B0Extensions,Markdown%3A%20Styles%EF%BC%8C%E7%84%B6%E5%90%8EAdd%20Item%EF%BC%8C%E5%8F%AF%E4%BB%A5%E6%B7%BB%E5%8A%A0%E5%BD%93%E5%89%8D%E5%B7%A5%E4%BD%9C "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文件中图片无法显示 - 稀土掘金](https://juejin.cn/post/7094968757256192037#:~:text=VSCode%E5%BC%80%E5%90%AF%E4%BE%A7%E8%BE%B9%E9%A2%84%E8%A7%88%EF%BC%8CMarkDown%E6%96%87%E4%BB%B6%E4%B8%AD%E5%9B%BE%E7%89%87%E6%97%A0%E6%B3%95%E6%98%BE%E7%A4%BA%20,%E6%89%93%E5%BC%80%E5%91%BD%E4%BB%A4%E6%A1%86%20%C2%B7%20%E6%90%9C%E7%B4%A2MarkDown%EF%BC%8C%E6%89%BE%E5%88%B0%E6%9B%B4%E6%94%B9%E9%A2%84%E8%A7%88%E5%AE%89%E5%85%A8%E8%AE%BE%E7%BD%AE%E3%80%82%20%C2%B7%20%E9%80%89%E6%8B%A9%E5%85%81%E8%AE%B8%E4%B8%8D%E5%AE%89%E5%85%A8%E5%86%85%E5%AE%B9%E5%8D%B3%E5%8F%AF%E3%80%82 "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代码):

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

greet("Markdown")

表格与任务列表

下面是一个表格示例:

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

任务列表示例:

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

链接与图片

这是一个链接示例: .

下面插入一张图片示例(Markdown 标志):

https://i-blog.csdnimg.cn/img_convert/2305ee5b7ed3fbb81af9df463c75d0ad.png


(本示例涵盖了 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!