从零开始创建并发布博客

一、创建博客项目 Link to 一、创建博客项目

你可以选择其一：

• 使用现有项目：直接在已克隆的仓库内工作（推荐）
• 创建全新 Astro 项目：

1
2
3
4
5
6
7
8

# 安装 pnpm（如未安装）
corepack enable

# 创建 Astro 项目
pnpm create astro@latest my-blog
cd my-blog
pnpm install
pnpm dev

二、写一篇新文章 Link to 二、写一篇新文章

在项目中，文章位于 src/content/blog/。你可以新建 .md（纯 Markdown）或 .mdx（可用组件）。

Frontmatter（文档头部） Link to Frontmatter（文档头部）

文章必须包含 Frontmatter，用于生成列表、路由和元数据：

1
2
3
4
5
6
7
8
9
10
11
12

---
title: "我的第一篇博客"
description: "一句话说明文章内容与价值"
pubDate: "Jan 29 2026"
image: /home.webp
categories:
  - tech
tags:
  - blog
  - getting-started
badge: Pin
---

选择 Markdown 或 MDX Link to 选择 Markdown 或 MDX

• .md：更轻量，适合普通文章
• .mdx：可引入组件（提醒、折叠、时间线等）

在 MDX 中引入组件示例：

1
2
3
4
5
6
7

import Info from "../../components/mdx/Info.astro";
import Warning from "../../components/mdx/Warning.astro";
import Success from "../../components/mdx/Success.astro";

<Info>这是信息提示</Info>
<Warning>这是注意事项</Warning>
<Success>这是成功/要点摘要</Success>

三、修改文章内容 Link to 三、修改文章内容

• 打开目标文件（位于 src/content/blog）直接编辑
• 修改 Frontmatter 与正文
• 保存后即可在本地预览中看到变化

四、书写格式建议 Link to 四、书写格式建议

• 标题层级：从 # 开始逐级递进，不要跳级
• 段落与块级元素之间空一行，避免渲染错乱
• 代码块使用三反引号并标注语言（如 python、bash）
• 列表缩进统一，表格包含表头分隔行

示例（代码块与列表）：

1
2

pnpm dev
pnpm build

1
2

def hello():
    print("hello blog")

• 图片资源放置于 public/image 等目录，使用绝对路径（如 /image/image1.jpg）

五、本地预览与构建 Link to 五、本地预览与构建

1
2
3
4
5
6
7
8

# 开发预览（本地）
pnpm dev

# 生产构建
pnpm build

# 本地预览构建产物
pnpm preview

六、推送到远程（Git） Link to 六、推送到远程（Git）

1
2
3
4

git status
git add .
git commit -m "docs: add new blog post"
git push

如需发布到平台（例如 Vercel/Netlify），按照平台指引连接你的 Git 仓库，自动构建并部署。

七、常见问题 Link to 七、常见问题

八、速查清单 Link to 八、速查清单