第 1 步：启动本地预览#

1
cd E:\GITHUB\firefly-replica
2
pnpm dev

启动后，浏览器打开本地地址，看着页面边改边预览。

第 2 步：新建或编辑文章文件#

这个项目真正读取的是：

1
src/content/posts/

你可以在这个目录里新建一个 Markdown 文件，比如：

1
src/content/posts/22.md

第 3 步：先写好文章头信息#

1
---
2
title: 文章标题
3
published: 2026-04-19
4
description: 用一句话说明这篇文章写什么
5
tags: [学习笔记]
6
category: 博客搭建
7
author: Coldairboy
8
image: ./images/firefly1.avif
9
---

第 4 步：按这个结构写正文#

1
# 文章大标题
2

3
开头先用 1 到 2 句话说明这篇文章讲什么。
4

5
## 第一部分
6

7
正文内容……
8

9
## 第二部分
10

11
- 要点 1
12
- 要点 2
13
- 要点 3
14

15
## 总结
16

17
最后写一句总结。

第 5 步：检查效果#

重点看这几个地方：

• 标题有没有层级错乱
• 列表有没有挤在同一行
• 代码块有没有完整包住
• 图片能不能正常显示
• 链接能不能点开

第 6 步：推送到 GitHub Pages#

如果你已经改好内容，直接运行：

1
cd E:\GITHUB\firefly-replica
2
.\publish-blog.bat

如果你之前已经提交过，只是推送失败了，就运行：

1
cd E:\GITHUB\firefly-replica
2
.\push-only.bat

1. 标题#

1
# 一级标题
2
## 二级标题
3
### 三级标题
4
#### 四级标题

提醒：

• 一篇文章通常只保留一个 # 一级标题
• 不要一级标题后直接跳到四级标题
• 层级尽量按顺序来，看起来更清楚

2. 强调文字#

1
**粗体**
2
*斜体*
3
***粗斜体***
4
~~删除线~~
5
`行内代码`

适合怎么用：

• 粗体：强调重点
• 行内代码：写命令、文件名、变量名时很好用
• 不要一整段都加粗，不然反而看不出重点

3. 无序列表#

1
- 第一项
2
- 第二项
3
- 第三项

4. 有序列表#

1
1. 第一步
2
2. 第二步
3
3. 第三步

提醒：

• 1. 后面要有空格
• 如果序号写在同一行，Markdown 可能不会正确识别
• 子列表要缩进

1
1. 第一步
2
2. 第二步
3
   1. 子步骤一
4
   2. 子步骤二
5
3. 第三步

5. 链接#

1
[OpenAI](https://openai.com)
2
[GitHub](https://github.com "GitHub 官网")

提醒：

• 方括号里放显示文字
• 小括号里放网址
• 地址最好复制后顺手点开试一次

6. 图片#

1
![图片说明](./images/example.jpg)

提醒：

• ! 不能漏
• 图片说明建议写上，方便阅读和 SEO
• 路径写错是最常见问题

7. 引用#

1
> 这是一段引用内容
2
> 可以连续写多行

适合用在：

• 摘录一句原话
• 写提示语
• 写总结结论

8. 代码块#

普通代码块：

1
```
2
这里放普通代码
3
```

带语法高亮的代码块：

1
```javascript
2
console.log("Hello");
3
```
4

5
```bash
6
pnpm dev
7
```

提醒：

• 代码块前后空一行更稳
• 开始和结束的反引号数量必须一致
• 写命令推荐用 bash 或 powershell
• 写配置推荐用 json、yaml、html、css

9. 表格#

1
| 名称 | 说明 | 备注 |
2
| --- | --- | --- |
3
| title | 文章标题 | 必填 |
4
| published | 发布日期 | 必填 |
5
| tags | 标签 | 可选 |

提醒：

• 表头和分隔线不要漏
• 列太多时，手机上会不太好看
• 新手前期不建议做太复杂的表格

10. 分隔线#

1
---

适合用来分开两个大段落，但不要一篇文章到处乱插。

1. 任务列表#

1
- [x] 已完成
2
- [ ] 未完成
3
- [ ] 待补充

适合写待办清单、教程步骤进度。

2. 脚注#

1
这里有一个说明[^1]
2

3
[^1]: 这是脚注内容

适合补充说明，不打断正文阅读。

3. 数学公式#

行内公式：

1
$E = mc^2$

块级公式：

1
$$
2
E = mc^2
3
$$

4. Mermaid 图表#

1
```mermaid
2
graph TD
3
    A[开始] --> B[写文章]
4
    B --> C[本地预览]
5
    C --> D[推送发布]
6
```

适合画简单流程图。第一次使用时，如果页面不显示，先检查主题是否已开启 Mermaid 支持。

5. 提示框#

1
::: tip
2
这是提示信息
3
:::
4

5
::: warning
6
这是警告信息
7
:::

适合把“重点提醒”单独强调出来。

1. 少空行#

错误示例：

1
## 标题
2
- 列表1
3
- 列表2

虽然有时也能显示，但复杂一点时容易乱。更稳的写法是段落之间留空行。

2. 代码块没关上#

如果少了结尾的三个反引号，后面整段内容都可能跑进代码框。

3. 把中文符号当成英文符号#

最常见的是：

• 把 ` 写成中文引号
• 把 : 写成中文冒号
• 把 () 写成全角括号

这些都会影响语法识别。

4. 图片路径写错#

如果文章和图片不在同一目录，路径就不能随便写。看不到图片时，优先检查路径，而不是先怀疑主题坏了。

5. Frontmatter 写串行#

比如这种就是错的：

1
author: Coldairboy image: ./images/firefly1.avif

正确写法必须一行一个字段：

1
author: Coldairboy
2
image: ./images/firefly1.avif

6. 文件改了，但网页没变#

这在这个项目里通常有 3 个原因：

1. 你改的是 src/content/，但站点实际读取的是 src/content/posts/
2. 本地服务没刷新成功
3. 改完了但还没推送到 GitHub

Q: 为什么我写了序号，却没有显示成列表？#

先检查这 3 点：

1. 1. 后面有没有空格
2. 每一项是不是单独一行
3. 前后有没有被代码块包住

Q: 为什么代码没有高亮？#

通常是因为没有写语言标记，比如：

1
```bash
2
pnpm dev
3
```

Q: 为什么图片不显示？#

按这个顺序检查最省事：

1. 文件在不在
2. 路径对不对
3. 文件名大小写对不对
4. 本地预览能不能看到

Q: 为什么文章顺序不对？#

文章列表主要看 published 日期。日期越晚，通常越靠前。