如何在 Astro 中撰写文章
Astro 提供了强大的内容管理系统，让撰写和管理博客文章变得简单高效。本文将详细介绍如何在 Astro 项目中创建和发布文章。
文章文件结构
存放位置
所有文章都应该存放在 src/content/blog/ 目录下。Astro 会自动扫描这个目录中的 Markdown 文件，并将它们转换为博客文章。
文件命名规则
- 文件名使用小写字母和连字符，例如：
my-first-post.md - 文件名将作为文章的 URL 路径，所以要有意义且简洁
- 避免使用空格和特殊字符
Front Matter 配置
每篇文章都必须以 Front Matter 开头，这是用三个连字符包围的 YAML 格式元数据：
---
title: "文章标题"
description: "文章描述"
publishDate: 2025-12-26
tags: ["标签1", "标签2"]
image: "/path/to/image.jpg"
---必填字段
title：文章标题
- 显示在文章页面和博客列表中
- 支持 HTML 实体和特殊字符
description：文章描述
- 简要概括文章内容，通常 1-2 句话
- 用于 SEO 和社交媒体分享
publishDate：发布日期
- 格式：YYYY-MM-DD
- 用于文章排序和归档
- 只显示发布日期不晚于当前日期的文章
可选字段
tags：标签数组
- 用于文章分类和标签云
- 格式：[“标签1”, “标签2”, “标签3”]
- 可以省略，文章将不显示任何标签
image：文章封面图片
- 图片路径相对于
public/目录 - 建议尺寸：1200x630 像素（社交媒体分享优化）
- 支持 JPG、PNG、WebP 等格式
Markdown 内容编写
基本语法
# 一级标题
## 二级标题
### 三级标题
**粗体文本** 和 __粗体文本__
*斜体文本* 和 _斜体文本_
***粗斜体文本***
- 无序列表项 1
- 无序列表项 2
- 嵌套列表项
- 另一个嵌套项
1. 有序列表项 1
2. 有序列表项 2
[链接文本](https://example.com)
代码块
行内代码：const variable = 'value';
代码块：
function greet(name) {
console.log(`Hello, ${name}!`);
}带语法高亮的代码块：
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)引用和表格
这是引用文本 可以有多行
| 列1 | 列2 | 列3 |
|---|---|---|
| 数据1 | 数据2 | 数据3 |
| 数据4 | 数据5 | 数据6 |
图片处理
图片存放位置
- 所有静态资源都应放在
public/目录下 - 建议在
public/中创建子目录，如public/images/blog/
图片引用方式
在 Front Matter 中：
image: "/images/blog/my-article-cover.jpg"在文章内容中：
图片优化建议
- 使用 WebP 格式以获得更好的压缩率
- 提供多种尺寸的图片以适应不同设备
- 为图片添加有意义的 alt 文本以提高可访问性
文章发布流程
1. 创建文章文件
在 src/content/blog/ 目录下创建新的 .md 文件
2. 编写 Front Matter
填写必要的元数据信息
3. 撰写文章内容
使用 Markdown 语法编写文章正文
4. 预览和测试
运行 npm run dev 启动开发服务器，在浏览器中预览文章
5. 发布文章
文章会自动出现在博客列表页面，无需额外配置
最佳实践
内容组织
- 使用清晰的文章结构，包含适当的标题层级
- 每个段落保持简洁，专注于一个观点
- 使用列表、表格和图片来增强可读性
SEO 优化
- 在标题和描述中使用相关关键词
- 合理使用 H1、H2、H3 标题
- 为所有图片添加有意义的 alt 文本
代码示例
- 使用语法高亮来提高代码可读性
- 提供完整的、可运行的代码示例
- 为复杂代码添加说明和注释
常见问题
Q: 文章没有显示在博客列表中？ A: 检查 publishDate 是否设置为未来日期，Astro 不会显示未来发布的文章。
Q: 图片无法显示？
A: 确保图片路径正确且以 / 开头，图片文件确实存在于 public/ 目录中。
Q: 标签点击没有反应？ A: 标签页面功能可能需要额外实现，请检查路由配置。
Q: 如何设置文章作者？
A: 可以在 Front Matter 中添加 author 字段，然后在模板中显示。
通过遵循以上指南，您就可以在 Astro 中轻松创建专业的博客文章了。记住，好的内容不仅需要技术实现，更需要有价值的思考和表达。