Fuwari 博客，精美的静态博客

Fuwari 是一个基于 Astro 构建的精美静态博客模板，拥有流畅的动画、响应式设计和丰富的功能。本文将详细介绍如何从零开始部署你的 Fuwari 博客，并展示其强大的 Markdown 扩展语法。

📋 前置要求#

在开始之前，请确保你的系统已安装以下工具：

Node.js：版本 >= 20
pnpm：版本 >= 9（推荐使用 pnpm 作为包管理器）

安装 pnpm#

如果你还没有安装 pnpm，可以运行以下命令：

1
npm install -g pnpm

🚀 第一步：创建项目#

有多种方式可以创建 Fuwari 博客项目：

方式一：使用 GitHub 模板#

访问 Fuwari GitHub 仓库
点击 “Use this template” → “Generate a new repository”
为你的新仓库命名并创建

方式二：Fork 仓库#

访问 Fuwari GitHub 仓库
点击右上角的 “Fork” 按钮

方式三：使用命令行工具#

1
npm create fuwari@latest
2
# 或者
3
pnpm create fuwari@latest
4
# 或者
5
yarn create fuwari
6
# 或者
7
bun create fuwari@latest

📥 第二步：克隆项目并安装依赖#

创建仓库后，将项目克隆到本地：

1
git clone https://github.com/你的用户名/你的仓库名.git
2
cd 你的仓库名

安装项目依赖：

1
pnpm install
2
pnpm add sharp

注意：sharp 是一个图像处理库，用于图片优化，建议安装以提高性能。

⚙️ 第三步：配置博客#

编辑 src/config.ts 文件来个性化你的博客：

1
export const siteConfig: SiteConfig = {
2
  title: "你的博客标题",
3
  subtitle: "你的博客副标题",
4
  lang: "zh_CN",
5
  themeColor: {
6
    hue: 50,
7
    fixed: false,
8
  },
9
  // ... 其他配置项
10
};

在 astro.config.mjs 中配置你的网站 URL：

1
export default defineConfig({
2
  site: "https://你的域名.com",
3
  base: "/",
4
  trailingSlash: "always",
5
  // ... 其他配置
6
});

✍️ 第四步：创建第一篇文章#

使用以下命令创建新文章：

1
pnpm new-post 我的-first-文章

这将在 src/content/posts/ 目录下创建一个新的 Markdown 文件。编辑文件内容，文章的 frontmatter 如下：

1
---
2
title: 我的 First 文章
3
published: 2026-02-03
4
description: 这是我的第一篇文章
5
image: ./cover.jpg # 可选的封面图
6
tags: [标签1, 标签2]
7
category: 分类
8
draft: false # 设置为 true 可以保存为草稿
9
---

🧪 第五步：本地预览#

在部署之前，你可以先在本地预览博客效果：

1
pnpm dev

访问 http://localhost:4321 查看你的博客。

构建生产版本：

1
pnpm build

预览构建后的网站：

1
pnpm preview

🌐 第六步：部署到平台#

Vercel 部署（推荐）#

将代码推送到 GitHub
访问 Vercel 并登录
点击 “Add New Project”
导入你的 GitHub 仓库
Vercel 会自动检测 Astro 项目，点击 “Deploy”
等待部署完成，即可获得你的博客链接

Netlify 部署#

将代码推送到 GitHub
访问 Netlify 并登录
点击 “Add new site” → “Import an existing project”
选择你的 GitHub 仓库
构建命令设置为：pnpm build
发布目录设置为：dist
点击 “Deploy site”

GitHub Pages 部署#

创建 .github/workflows/deploy.yml 文件：

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches: [main]
6

7
jobs:
8
  deploy:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v4
12
      - uses: actions/setup-node@v4
13
        with:
14
          node-version: 20
15
          cache: "npm"
16
      - run: npm install -g pnpm
17
      - run: pnpm install
18
      - run: pnpm build
19
      - uses: peaceiris/actions-gh-pages@v3
20
        with:
21
          github_token: ${{ secrets.GITHUB_TOKEN }}
22
          publish_dir: ./dist

在 GitHub 仓库设置中，将 Pages 源设置为 gh-pages 分支
推送代码，GitHub Actions 会自动部署

Cloudflare Pages 部署#

将代码推送到 GitHub
访问 Cloudflare Pages
点击 “Create a project” → “Connect to Git”
选择你的 GitHub 仓库
构建命令：pnpm build
输出目录：dist
点击 “Save and Deploy”

Cloudflare Workers 部署#

如果你选择了 Cloudflare Workers 部署，项目已经包含了 wrangler.toml 配置文件：

1
name = "fuwari"
2
compatibility_date = "2026-02-03"
3

4
[assets]
5
directory = "./dist"

部署步骤：

1
# 构建项目
2
pnpm build
3

4
# 部署到 Cloudflare Workers
5
npx wrangler pages deploy dist

✨ Fuwari 核心特性#

🎨 精美的 UI 设计#

流畅的页面过渡动画
精心设计的配色方案
完全响应式布局，支持移动端
支持 明暗模式 切换

📑 自动目录生成#

文章会根据标题自动生成目录（TOC），支持滚动高亮和点击跳转。

🔍 内置搜索功能#

基于 Pagefind 的全文搜索功能，无需配置即可使用。

📡 RSS 订阅支持#

自动生成 RSS 订阅源，方便读者订阅。

🎯 评论功能#

支持集成多种评论系统。

💬 丰富的 Markdown 扩展语法#

Fuwari 支持多种 Markdown 扩展语法，让文章更加丰富多彩。

📝 Fuwari Markdown 扩展语法详解#

1. GitHub 仓库卡片#

你可以添加链接到 GitHub 仓库的动态卡片，仓库信息从 GitHub API 实时获取。

saicaca

fuwari

Waiting for api.github.com...

00K

Waiting...

使用方法：

1
::github{repo="<owner>/<repo>"}

示例：

1
::github{repo="saicaca/fuwari"}
2
::github{repo="vercel/next.js"}

2. 警告框（Admonitions）#

支持五种类型的警告框，用于突出显示重要信息。

Note - 注意#

NOTE
突出显示用户应该注意的信息，即使是在快速浏览时。

Tip - 提示#

TIP
帮助用户更成功的可选信息。

Important - 重要#

IMPORTANT
用户成功所必需的关键信息。

Warning - 警告#

WARNING
由于潜在风险而需要立即注意的关键内容。

Caution - 谨慎#

CAUTION
操作的负面潜在后果。

基本语法：

1
:::note
2
注意内容
3
:::
4

5
:::tip
6
提示内容
7
:::

自定义标题：

自定义标题
这是一个带有自定义标题的注释。

1
:::note[自定义标题]
2
这是一个带有自定义标题的注释。
3
:::

GitHub 语法支持：

NOTE
也支持 GitHub 风格的语法。

1
> [!NOTE]
2
> 这是 GitHub 风格的注释。
3

4
> [!TIP]
5
> 这是 GitHub 风格的提示。

3. 剧透（Spoiler）#

你可以在文本中添加剧透内容，鼠标悬停时显示。

内容是隐藏的 剧透内容！

1
内容 :spoiler[是隐藏的 **剧透内容**]！

4. Expressive Code 代码块#

Fuwari 使用 Expressive Code 提供强大的代码块功能，支持多种高亮和标记方式。

语法高亮#

Expressive Code 会自动根据语言标识符进行语法高亮。

1
console.log("这段代码是语法高亮的！");

使用方法：

1
```js
2
console.log("代码");
3
```

代码块标题#

使用 title 属性添加标题，或在代码第一行添加注释。

1
function hello() {
2
  console.log("Hello, World!");
3
}

1
<div>文件名注释示例</div>

使用方法：

1
```js title="文件名.js"
2
代码内容;
3
```
4

5
```html
6
<!-- 路径/文件名 -->
7
<div>内容</div>
8
```

终端框架#

自动检测 shell 类型（bash、powershell、sh 等），以终端风格展示命令。

1
echo "终端示例"

1
Write-Output "这个有标题！"

使用方法：

1
```bash
2
命令
3
```
4

5
```powershell title="终端标题"
6
命令
7
```

行高亮标记#

在语言标识符后添加花括号，指定行号或范围进行高亮。

1
// 第 1 行会被高亮
2
// 第 2 行普通
3
// 第 3-5 行会被高亮
4
console.log("第 3 行");
5
console.log("第 4 行");
6
console.log("第 5 行");

使用方法：

1
```js {1, 3-5}
2
代码;
3
```

行标记类型（ins、del）#

使用 del 和 ins 属性标记删除和插入的行。

1
function demo() {
2
  console.log("这行被标记为已删除");
3
  console.log("这行被标记为已插入");
4
  console.log("这行被标记为已插入");
5
  console.log("普通行");
6
}

使用方法：

1
```js del={2} ins={3-4}
2
代码;
3
```

行内文本标记#

在语言标识符后添加引号包裹要标记的文本。

1
function demo() {
2
  console.log("标记特定文本");
3
}

使用方法：

1
```js "要标记的文本"
2
代码;
3
```

正则表达式标记#

使用斜杠包裹正则表达式来匹配和标记文本。

1
console.log("单词 yes 和 yep 将被标记。");

使用方法：

1
```ts /正则表达式/
2
代码;
3
```

类似 diff 的语法#

使用 diff 语言标识符，+ 表示插入，- 表示删除。

1
这一行将被标记为已插入
2
这一行将被标记为已删除
3
这是一常规行

使用方法：

1
```diff
2
+新增行
3
-删除行
4
普通行
5
```

自动换行#

使用 wrap 属性启用或禁用自动换行。

1
// 启用自动换行
2
function getLongString() {
3
  return "这是一个非常长的字符串，会自动换行";
4
}

使用方法：

1
```js wrap
2
代码;
3
```
4

5
```js wrap=false
6
代码;
7
```

可折叠部分#

使用 collapse 属性指定要折叠的行范围，点击可展开/收起。


3 collapsed lines
1
// 这部分代码会被折叠
2
import { boilerplate } from "example";
3

4
// 这部分可见
5
console.log("可见代码");
6

2 collapsed lines
7
// 这部分也会被折叠
8
boilerplate.cleanup();

使用方法：

1
```js collapse={1-3, 7-9}
2
代码;
3
```

行号#

使用 showLineNumbers 启用行号，startLineNumber 设置起始行号。

1
// 显示行号
2
console.log("第 2 行");
3
console.log("第 3 行");

10
// 从第 10 行开始编号
11
console.log("第 11 行");

使用方法：

1
```js showLineNumbers
2
代码;
3
```
4

5
```js showLineNumbers startLineNumber=10
6
代码;
7
```

5. 数学公式#

支持 LaTeX 数学公式，包括行内公式和块级公式。

行内公式： $E = mc^2$

块级公式：

\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}

\begin{aligned} f(x) &= x^2 + 2x + 1 \\ &= (x + 1)^2 \end{aligned}

使用方法：

1
行内公式：$E = mc^2$
2

3
块级公式：
4

5
$$
6
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
7
$$

6. 图片查看器#

点击图片会自动打开 Lightbox 查看器，支持缩放和切换。

示例图片

使用方法： 使用标准 Markdown 图片语法即可，点击查看器会自动启用。

1
![图片描述](图片URL)

📝 常用命令#

命令	说明
`pnpm install`	安装依赖
`pnpm dev`	启动开发服务器
`pnpm build`	构建生产版本
`pnpm preview`	预览构建结果
`pnpm new-post <filename>`	创建新文章
`pnpm format`	格式化代码
`pnpm lint`	检查代码规范

🎯 总结#

通过以上步骤，你已经成功部署了自己的 Fuwari 博客！Fuwari 提供了丰富的功能和精美的设计，非常适合个人博客、技术文档等内容网站。

Fuwari 的主要优势#

零配置搜索：基于 Pagefind 的静态搜索，无需后端
丰富的 Markdown 扩展：支持警告框、代码高亮、数学公式等
优秀的性能：Astro 构建的静态站点，加载速度快
现代化设计：流畅的动画和精美的 UI
易于定制：清晰的配置文件和主题系统

如果你在部署过程中遇到任何问题，可以参考 Fuwari 官方文档或在 GitHub 上提交 Issue。

祝你博客写作愉快！🎉