Markdown 使用
Markdown 使用
Markdown 是一种轻量级标记语言，适合用来编写博客、笔记、文档和技术文章。它的核心思想是：用简单的符号表达文章结构，让内容更容易阅读、维护和发布。
在 VuePress 中，普通文章一般使用 .md 文件编写，文件内容会被自动转换成网页。
基础结构
一篇文章通常由两部分组成：页面信息和正文内容。
---
title: 文章标题
date: 2026-08-07
category:
- 使用指南
tag:
- Markdown
---
## 一级内容标题
这里写正文内容。
上方 --- 包起来的部分叫 Frontmatter，用来配置标题、日期、分类、标签等页面信息。
常用字段如下：
title: 文章标题
index: false
date: 2026-08-07
icon: edit
category:
- 使用指南
tag:
- Markdown
- 写作
标题
标题用 # 表示，# 越多，层级越低。
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
写文章时建议从 ## 开始写正文标题，因为页面标题通常已经由 Frontmatter 的 title 提供。
段落和换行
普通文字直接写即可。
这是第一段内容。
这是第二段内容。
Markdown 中空一行表示新段落。如果只是普通回车，很多情况下不会生成新的段落。
加粗、斜体和删除线
**加粗文字**
*斜体文字*
~~删除线文字~~
显示效果：
加粗文字
斜体文字
删除线文字
列表
无序列表使用 -：
- 第一项
- 第二项
- 第三项
有序列表使用数字：
1. 第一步
2. 第二步
3. 第三步
列表项不要随意混用缩进，否则可能导致渲染异常。
引用
引用使用 >：
> 这是一段引用内容。
适合放提示、备注、摘录等内容。
代码
行内代码使用反引号：
执行 `npm run docs:dev` 启动项目。
多行代码使用三个反引号，并建议写上语言类型：
```bash
npm install
npm run docs:dev
```
常见语言标识：
bash
js
ts
html
css
json
yaml
md
链接
链接语法：
[链接文字](https://example.com)
示例：
[访问 GitHub](https://github.com/)
如果链接到站内文章，建议使用相对路径：
[获取个人博客](createMyBlog.md)
图片
图片是文章中很常用的内容，可以用来放操作截图、效果图、流程图或示例图。
图片语法：
如果图片放在 VuePress 的 public 目录，例如：
src/.vuepress/public/myBlog/markdown/demo-image.png
在文章中可以这样引用：
也可以根据当前文章位置使用相对路径：
建议图片文件名尽量使用英文、数字和短横线，例如：
github-create-repo.png
cloudflare-build-settings.png
markdown-writing-flow.png
这样可以减少路径编码和部署后图片加载失败的问题。
表格
表格写法：
| 配置项 | 说明 |
| --- | --- |
| Build command | npm run docs:build |
| Output directory | src/.vuepress/dist |
显示效果：
| 配置项 | 说明 |
|---|---|
| Build command | npm run docs:build |
| Output directory | src/.vuepress/dist |
表格前后建议空一行，内容较长时可以考虑改成列表，避免移动端显示太挤。
分割线
使用三个短横线：
---
分割线适合用于分隔不同主题，但不要过度使用。
任务列表
- [x] 已完成
- [ ] 未完成
适合写计划、清单和待办事项。
VuePress 提示容器
VuePress 支持提示容器，适合在文章中突出说明。
::: tip
这是提示内容。
:::
::: warning
这是警告内容。
:::
::: danger
这是危险提示。
:::
可以用来写注意事项、常见问题和重要提醒。
Badge 标签
可以在文章中使用 Badge：
<Badge text="推荐" type="tip" />
<Badge text="注意" type="warning" />
适合标注状态，但不要在正文里放太多，否则会影响阅读。
写作注意事项
- 标题层级要清晰，不要从
##直接跳到####。 - 段落之间空一行，让源码和页面都更容易阅读。
- 代码块一定要闭合，三个反引号开头就要用三个反引号结尾。
- 图片路径要确认真实存在，大小写也要一致。
- 文件名建议使用英文，例如
createMyBlog.md，减少部署时的路径问题。 - 不要把
node_modules、.vuepress/dist这类依赖和构建产物提交到 Git。 - 外部链接建议使用完整地址，例如
https://github.com/。 - 一篇文章只围绕一个主题写，内容太长可以拆成多篇。
- 文章写完后执行
npm run docs:build，确认可以正常构建。 - 提交前执行
git status，确认没有误提交无关文件。
推荐文章结构
技术类文章可以按下面结构写：
---
title: 文章标题
date: 2026-08-07
category:
- 使用指南
tag:
- Markdown
---
## 背景
说明为什么要写这篇文章。
## 准备工作
列出需要安装的软件、账号或配置。
## 操作步骤
按顺序写具体步骤，每一步配命令或截图。
## 常见问题
记录容易踩坑的地方和解决办法。
## 总结
简单说明最终完成了什么。
常用模板
命令说明模板
执行命令：
```bash
npm run docs:build
```
命令作用：生成 VuePress 静态文件。
截图预留模板
::: info 截图预留
这里放操作截图：`src/.vuepress/public/myBlog/markdown/example.png`
:::
注意事项模板
::: warning
修改配置后需要重新构建并部署，否则线上页面不会变化。
:::
小结
Markdown 的重点不是语法复杂，而是结构清楚。写博客时先把标题、步骤、代码、截图位置整理好，再补充细节，文章会更容易维护。