1.1 什么是Mizuki主题？#

Mizuki是一个基于Astro的现代化静态博客模板，由社区开发者创建和维护。它结合了Astro的性能优势和现代化的设计理念，提供了丰富的功能和灵活的配置选项。

1.2 主要特点#

• 现代化设计：采用简洁、美观的现代设计风格
• 高性能：基于Astro的静态站点生成，加载速度快
• 丰富的功能：支持文章分类、标签、搜索、评论等功能
• 响应式布局：适配不同屏幕尺寸的设备
• 易于定制：提供灵活的配置选项和主题设置
• 多语言支持：支持国际化和多语言内容

1.3 适用场景#

• 个人博客：分享个人生活、技术心得等
• 技术博客：发布技术文章、教程等
• 知识库：整理和分享专业知识
• 系列文档：创建结构化的文档内容

2.1 环境准备#

在使用Mizuki主题之前，你需要安装以下软件：

• Node.js：版本18.0或更高
• npm或Yarn：包管理器
• Git：版本控制工具

2.2 安装主题#

方法1：使用模板创建

1. 访问Mizuki主题的GitHub仓库
2. 点击”Use this template”按钮
3. 填写仓库信息并创建新仓库
4. 克隆新仓库到本地

方法2：直接克隆

1
git clone https://github.com/mizuki-next/astro-theme-mizuki.git
2
cd astro-theme-mizuki
3
npm install

2.3 基本配置#

配置文件：主题的主要配置文件是src/config.ts，你可以在这里修改网站的基本信息。

修改网站信息：

1
export const SITE = {
2
  name: '我的博客',
3
  domain: 'blog.example.com',
4
  description: '这是我的个人博客',
5
  author: '作者名称',
6
  email: 'author@example.com',
7
  // 其他配置...
8
};

2.4 启动开发服务器#

1
npm run dev

然后在浏览器中访问http://localhost:3000查看你的博客。

3.1 创建文章#

文章目录：文章存放在src/content/posts目录中。

创建新文章：在src/content/posts目录中创建一个新的Markdown文件，例如my-first-post.md。

文章格式：

1
---
2
title: 我的第一篇文章
3
published: 2026-02-26
4
pinned: false
5
description: 这是我的第一篇文章
6
 tags: [Tag1, Tag2]
7
category: Category
8
licenseName: "CC BY-NC-SA 4.0"
9
author: 作者名称
10
sourceLink: ""
11
draft: false
12
---
13

14
# 文章标题
15

16
文章内容...

3.2 文章分类#

分类配置：在src/content/categories目录中创建分类文件。

创建分类：创建src/content/categories/tech.md文件：

1
---
2
title: 技术
3
---

3.3 文章标签#

标签使用：在文章的Frontmatter中添加tags字段，指定文章的标签。

示例：

1
---
2
tags: [JavaScript, React, Frontend]
3
---

3.4 系列文章#

创建系列：在src/content/series目录中创建系列文件。

创建系列文件：创建src/content/series/react-tutorial.md文件：

1
---
2
title: React入门教程
3
description: 从基础到高级的React学习系列
4
---

在文章中引用系列：

1
---
2
series: react-tutorial
3
---

4.1 配置选项#

主题配置：在src/config.ts文件中，你可以修改主题的各种配置选项。

主要配置选项：

• SITE：网站基本信息
• NAVIGATION：导航菜单配置
• SOCIAL：社交媒体链接
• COMMENT：评论系统配置
• SEARCH：搜索功能配置
• ANALYTICS： analytics配置

4.2 自定义样式#

样式文件：主题的样式文件位于src/styles目录中。

修改全局样式：编辑src/styles/global.css文件。

添加自定义样式：在src/styles目录中创建新的样式文件，并在需要的地方引入。

4.3 自定义组件#

组件目录：主题的组件位于src/components目录中。

修改现有组件：编辑src/components目录中的组件文件。

创建新组件：在src/components目录中创建新的组件文件。

4.4 自定义页面#

页面目录：主题的页面位于src/pages目录中。

修改现有页面：编辑src/pages目录中的页面文件。

创建新页面：在src/pages目录中创建新的页面文件。

5.1 文章功能#

• 文章分类：将文章按照分类组织
• 文章标签：为文章添加标签，方便分类和搜索
• 系列文章：将相关文章组织成系列
• 文章搜索：支持基于内容的搜索
• 文章评论：集成评论系统

5.2 网站功能#

• 导航菜单：自定义顶部导航菜单
• 社交媒体链接：添加社交媒体图标和链接
• 页脚信息：自定义页脚内容
• 404页面：自定义404错误页面
• 站点地图：自动生成站点地图
• RSS订阅：生成RSS订阅 feed

5.3 性能优化#

• 静态生成：使用Astro的静态站点生成功能
• 图片优化：自动优化图片大小和格式
• 代码分割：按需加载JavaScript代码
• 缓存策略：合理的缓存设置

6.1 集成第三方服务#

评论系统：

• Disqus
• Utterances
• Giscus

Analytics：

• Google Analytics
• Baidu Analytics
• Matomo

搜索服务：

• Algolia
• Local search

6.2 国际化#

多语言支持：Mizuki主题支持多语言内容。

配置语言：在src/config.ts文件中配置支持的语言。

创建多语言内容：在src/content目录中为不同语言创建对应的内容文件。

6.3 SEO优化#

元标签：主题会自动为每个页面生成合适的元标签。

结构化数据：支持添加JSON-LD结构化数据。

sitemap.xml：自动生成站点地图文件。

robots.txt：自动生成robots.txt文件。

6.4 部署优化#

部署到Vercel：

1. 连接GitHub仓库到Vercel
2. 配置构建命令：npm run build
3. 配置输出目录：dist
4. 点击”Deploy”按钮

部署到Netlify：

1. 连接GitHub仓库到Netlify
2. 配置构建命令：npm run build
3. 配置发布目录：dist
4. 点击”Deploy site”按钮

部署到GitHub Pages：

1. 创建GitHub Actions工作流文件
2. 配置构建和部署步骤
3. 推送到GitHub仓库

7.1 内容管理#

• 保持内容结构清晰：使用合适的标题层级和段落结构
• 添加合适的标签：为文章添加相关的标签，方便分类和搜索
• 使用系列功能：将相关文章组织成系列，提高内容的连贯性
• 定期更新内容：保持博客的活跃度和新鲜度

7.2 性能优化#

• 优化图片：使用合适的图片格式和大小
• 减少不必要的脚本：只加载必要的JavaScript代码
• 使用CDN：为静态资源使用CDN加速
• 启用缓存：合理配置缓存策略

7.3 SEO优化#

• 使用合适的标题：为每个页面使用清晰、描述性的标题
• 编写优质内容：创建有价值、原创的内容
• 添加内部链接：在文章中添加相关的内部链接
• 提交站点地图：将站点地图提交给搜索引擎

7.4 社区互动#

• 添加评论系统：鼓励读者评论和互动
• 分享到社交媒体：添加社交媒体分享按钮
• 参与社区讨论：加入Mizuki主题的QQ群或Discord频道
• 贡献代码：如果你发现bug或有改进建议，可以向GitHub仓库提交PR

8.1 如何添加新的分类？#

在src/content/categories目录中创建一个新的Markdown文件，文件名即为分类的slug，文件内容包含分类的标题。

8.2 如何添加新的标签？#

在文章的Frontmatter中添加tags字段，指定文章的标签。标签会自动在网站中创建。

8.3 如何创建系列文章？#

在src/content/series目录中创建一个新的Markdown文件，文件名即为系列的slug，文件内容包含系列的标题和描述。然后在文章的Frontmatter中添加series字段，指定文章所属的系列。

8.4 如何配置评论系统？#

在src/config.ts文件中，修改COMMENT配置项，选择并配置你想要使用的评论系统。

8.5 如何部署博客？#

Mizuki主题支持部署到各种静态网站托管服务，如Vercel、Netlify、GitHub Pages等。根据你的选择，按照相应的部署指南进行操作。

9.1 官方资源#

• GitHub仓库：https://github.com/mizuki-next/astro-theme-mizuki
• 文档：https://docs.mizuki.mysqil.com
• Discord频道：https://discord.gg/MqW6TcQtVM

9.2 社区支持#

• QQ群：1007524064 (主题交流群)
• GitHub Issues：在GitHub仓库中提交问题和建议
• Discord讨论：在Discord频道中与其他用户交流

9.3 学习资源#

• Astro官方文档：https://docs.astro.build
• Markdown指南：https://www.markdownguide.org
• 前端开发资源：各种前端开发教程和文档