Astro 博客主题使用指南

环境要求

• Node.js >= 20.0.0
• 包管理器：推荐使用 pnpm 或 yarn

安装步骤

1. 克隆项目

   git clone https://github.com/babybluue/astro-blog-theme
   cd astro-blog-theme

2. 安装依赖

   pnpm install
   # 或
   yarn install

3. 启动开发服务器

   pnpm dev
   # 或
   yarn dev

4. 访问博客 打开浏览器访问 http://localhost:4321 即可预览博客。

文章目录结构

博客支持两种内容类型：

• src/data/blogs/ - 正式发布的博客文章
• src/data/notes/ - 笔记和草稿内容

创建新文章

使用内置脚本快速创建文章：

# 在 drafts 目录创建草稿
pnpm run new --title='文章标题' --dir=drafts

# 在 blogs 目录创建正式文章
pnpm run new --title='文章标题' --dir=blogs

文章头信息配置

每篇文章都需要在文件顶部添加 YAML 头信息：

---
title: 文章标题
date: 2024-11-14T02:59:57.109Z
abbrlink: c3009907 # 文章唯一标识符
tags:
  - 标签1
  - 标签2
description: '文章描述'
cover: '@images/cover.jpg' # 可选：文章封面图
---

网站信息配置

在 constant.ts 文件中修改网站基本信息：

export const config = {
  postsPerPage: 12, // 每页文章数量
  siteName: '博客名称',
  author: '作者名称',
  language: 'zh-CN', // 语言设置
}

静态资源管理

• 网站图标：替换 public/favicon.svg
• PWA 图标：更新 public/pwa-*.png 系列图标
• 文章图片：将图片放在 src/data/images/ 目录下

核心功能

• 🚀 极速性能：基于 Astro 的静态站点生成，页面加载速度极快
• 📱 PWA 支持：可安装为桌面应用，支持离线访问
• 🔍 全文搜索：基于 Pagefind 的客户端搜索功能
• 🌙 深色模式：自动适配系统主题，支持手动切换
• 📱 响应式设计：完美适配各种设备尺寸
• 🎨 现代化 UI：基于 TailwindCSS 的精美界面设计
• 📊 SEO 优化：自动生成 sitemap，支持 meta 标签优化
• 🔗 自动链接：外部链接自动添加 nofollow 和 target="_blank"

技术栈

• 框架：Astro 5.x
• 样式：TailwindCSS 4.x
• 搜索：Pagefind
• PWA：Vite PWA
• 代码高亮：Shiki
• 构建工具：Vite

基础文本格式

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

**粗体文本** 和 _斜体文本_
~~删除线文本~~ 和 `行内代码`
==高亮文本== 和 ++下划线文本++

- 无序列表项 1
- 无序列表项 2
  - 嵌套列表项

1. 有序列表项 1
2. 有序列表项 2

- [x] 已完成的任务
- [ ] 未完成的任务
- [x] 另一个已完成的任务

引用和注释

> 这是一个引用块
> 可以包含多行内容
>
> 支持**粗体**和*斜体*格式

这是一个脚注示例[^1]，可以添加多个脚注[^2]。

[^1]: 这是第一个脚注的内容

[^2]: 这是第二个脚注的内容

> [!NOTE]
> 有用的信息，用户应该了解的内容

> [!TIP]
> 有用的建议，帮助用户更好地完成任务

> [!IMPORTANT]
> 重要信息，用户需要了解的关键内容

> [!WARNING]
> 警告信息，需要用户立即注意以避免问题

> [!CAUTION]
> 谨慎提醒，关于某些操作的风险或负面结果

代码相关

使用 `console.log()` 来输出调试信息

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`)
}
```

```ts {1-3}
title: 关于这个博客主题
date: 2024-11-14T02:59:57.109Z
abbrlink: c3009907
tags:
- Astro
- Theme
- Blog
description: '这是一个使用 Astro 框架搭建的博客。'
cover: '@images/c3009907.png'
```

图片展示

Lighthouse 性能测试显示该主题具有优秀的加载性能

构建项目

# 构建生产版本
pnpm build

# 预览构建结果
pnpm preview

部署平台

本主题支持多种部署平台：

自定义域名

在部署平台配置自定义域名，并更新 constant.ts 中的 site 变量。

修改颜色主题

在 src/styles/global.css 中自定义 CSS 变量：

:root {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --color-accent: #f59e0b;
}

如果你觉得这个主题有用，请给个 ⭐ Star 支持一下！