如何发布一篇博客

写在前面#

这个网站的博客文章放在 src/content/blog/ 目录下。每一篇文章本质上都是一个 Markdown 文件，写好内容之后，网站会自动把它渲染成博客页面。

如果文章不需要图片，只创建一个 .md 文件就可以；如果文章需要配图或其他资源，可以创建一个同名文件夹，把文章写在里面的 index.md 中。

创建文章#

最简单的方式是在 src/content/blog/ 下面新建一个 Markdown 文件，例如：

src/content/blog/my-new-blog.md

文件名会影响文章链接。比如这个文件最终会生成类似这样的路径：

/blog/my-new-blog

如果你希望链接更清晰，可以用英文短横线命名，例如：

how-to-learn-llm.md
reading-notes-transformer.md
my-first-project.md

编写 Frontmatter#

每篇博客开头都需要写一段配置，叫做 Frontmatter。它用来描述文章标题、发布时间、摘要、标签等信息。

一个基本模板如下：

---
title: 我的新博客
publishDate: 2026-07-03 20:00:00
description: '这是一篇文章摘要，会出现在博客列表或搜索结果中。'
tags:
  - blog
  - life
language: '中文'
draft: false
comment: false
---

常用字段含义：

如果 draft: true，这篇文章通常不会作为正式文章发布。写完准备公开时，把它改成：

draft: false

如果暂时不想开启评论，可以写：

comment: false

编写正文#

Frontmatter 下面就是正文。正文使用 Markdown 语法，例如：

## 第一节标题

这里写正文内容。

### 小标题

- 列表项一
- 列表项二

```ts
console.log('Hello, blog!')
```

写博客时可以先把内容分成几个部分：

1. 这篇文章想解决什么问题
2. 背景是什么
3. 具体过程是什么
4. 自己有什么理解或总结
5. 以后还想继续探索什么

这样文章会更清楚，也更容易坚持写下去。

预览文章#

本地启动开发服务：

bun dev

然后打开：

http://localhost:4321/blog

如果文章已经显示在博客列表中，说明它被网站识别到了。点击文章标题，就可以进入详情页预览排版。

如果没有显示，可以检查：

• 文件是否放在 src/content/blog/ 下
• Frontmatter 有没有语法错误
• draft 是否被设置成了 true
• 文件扩展名是不是 .md 或 .mdx

发布到线上#

本地确认没有问题后，先运行一次构建：

bun run build

如果构建通过，就可以提交代码：

git add .
git commit -m "Add new blog post"
git push

推送到 GitHub 后，Vercel 会自动重新部署网站。部署完成后，线上博客页面就会出现这篇新文章。

一个建议#

刚开始写博客时，不必追求每篇都很完整。可以先把博客当作自己的学习记录：今天学到了什么，遇到了什么问题，最后怎么解决的。

长期来看，这些零散记录会慢慢连成一条线。它会记录你如何理解技术，也会记录你如何理解自己。