1.1 项目文件准备#

Fuwari 由 saicaca 基于 Astro 二次开发，项目地址：https://github.com/saicaca/fuwari，相对原版对样式及功能进行了一定调整。为后续部署项目方便，可在本地使用git clone命令将项目文件克隆至本地。

1
git clone https://github.com/saicaca/fuwari.git

拉取项目文件后，进入项目目录，修改相关配置文件（主要是修改config.ts和astro.config.mjs），也可以根据需要修改项目名称及其他相关配置。

TIP

后续会重新推送到个人仓库，所以建议修改项目名称为自己的项目名称。 同时，项目中也包含了中文的部署说明，可参考项目中的README.md文件（其实项目文档介绍过于简单，建议继续往下看）。

1.2 本地预览运行#

项目文件准备完成后，使用vscode打开项目目录，安装相关依赖（建议使用pnpm），并运行项目。

1
cd fuwari
2
# 安装依赖
3
pnpm install
4
# 按照开发模式运行项目
5
pnpm run dev

执行完成后，一般会弹出项目运行地址（默认是http://localhost:4321），在浏览器中打开该地址，即可预览项目运行效果。

1
 astro  v5.13.10 ready in 4925 ms
2

3
┃ Local    http://localhost:4321/
4
┃ Network  use --host to expose

NOTE

在本地预览运行项目时，可根据需要修改src目录下的config.ts文件，修改项目名称、描述、作者等相关配置。在此模式下，修改后的配置会实时生效，无需重启项目。可方便随时调整个性化设置。

与其他前端项目类似，fuwari项目用到的执行脚本可在项目根目录下的package.json文件中查看。

1
# 主要用到一下命令
2
pnpm run dev # 按照开发模式运行项目
3
pnpm run build # 构建项目,生成静态文件至dist目录，可用于部署至静态站点服务（如vercel）
4
pnpm run preview # 预览构建项目
5
pnpm run new-post "博客标题" # 新建博客，会在src/content/posts目录下新建一个md文件，文件名格式为博客标题.md

IMPORTANT

dev模式和build模式下相比其他项目，fuwrari项目的博客如果是草稿状态，在dev模式下是会显示的，而在build及preview模式下不会显示。

2.1 新建博客#

在命令终端下，执行以下命令新建一个博客文件（默认会在当前目录下新建一个md文件，文件名格式为博客标题.md）。

1
pnpm run new-post "博客标题"

执行完成后，会在src/content/posts目录下生成一个新的md文件，打开该文件，按照markdown语法编写博客内容即可。博客内容编写完成后，执行开发模式运行项目，即可在本地预览博客效果。

1
# 默认生成的博客文件包含头部信息如下，可根据需要修改，不能删除（部分属性可以，但是结构不能改变）
2
---
3
title: Draft Example      # 博客标题
4
published: 2022-07-01     # 博客发布时间
5
tags: [Markdown, Blogging, Demo]     # 博客标签
6
category: Examples     # 博客分类
7
draft: true     # 博客是否为草稿状态
8
---

注意：项目默认有一些介绍示例的博客，新建博客后需要删除这些示例博客（当然也可以保留，设置为草稿状态即draft: true），否则在部署后会显示这些示例博客。注意，博客的md文件---之前不能出现其它内容，否则会导致博客内容解析错误。

2.2 创建远程仓库（对应本地项目）#

可以登录github账号，或gitlab账号，创建一个新的仓库（建议仓库名称与项目名称一致），并将本地项目文件推送至该仓库。 博主在为了github账号便于管理，采用新建的gitlab账号，将项目文件推送至gitlab仓库，仓库名称建议与项目名称一致。

TIP

无论使用github还是gitlab，建立的仓库最好选择空仓库（不包含任何文件），避免后续推送项目时出现冲突，若出现冲突，可根据提示进行解决。 在博主使用gitlab账号创建仓库时，就因为未注意默认配置导致生成了一个readme.md文件，导致后续推送项目时出现冲突。且后续推送因仓库默认有保护，需解除保护，才能成功推送项目，切记！！！

同步仓库文件 在本地项目目录下，执行以下命令将项目文件推送至远程仓库。

1
git add .
2
git commit -m "Initial commit" # 初始化提交
3
# 推送项目文件至远程仓库
4
git remote add origin <远程仓库地址> # 添加远程仓库地址
5
# 在使用gitlab时，会要求你必须配置ssh密钥，否则会推送失败，按照提示或参考gitlab文档配置ssh密钥即可，一般要放在c:\Users\Administrator\.ssh目录下(这是在windows系统下)
6
git push origin main # 推送项目文件至远程仓库的main分支

提交项目文件后，即可在远程仓库中查看项目文件。

2.3 增量推送博客#

在本地项目目录下，执行以下命令将增量的博客文件推送至远程仓库。

1
pnpm run new-post "博客标题" # 新建博客，会在src/content/posts目录下新建一个md文件，文件名格式为博客标题.md，编辑该文件，编写博客内容即可。
2
git add . # 添加增量的博客文件
3
git commit -m "Add new post" # 增量提交
4
git push origin main # 推送增量博客文件至远程仓库的main分支

执行完成后，即可在远程仓库中查看增量的博客文件。

3.1 vercel静态部署介绍#

Vercel 是一个流行的前端部署平台，支持静态网站和无服务器函数的部署。它与 Astro 等静态站点生成器兼容良好，能够轻松地将静态博客站点部署到互联网上。Vercel 提供了简单的界面和强大的功能，使得部署过程变得非常便捷。 登录vercel账号，点击“New Project”按钮，选择“Import Git Repository”，输入项目的git仓库地址，点击“Import”按钮，即可将项目导入到vercel平台。

3.2 创建项目构建#

在导入项目后，vercel会自动检测项目的框架类型，并生成相应的构建设置。对于fuwari项目，vercel会识别为Astro项目，并自动填写构建命令和输出目录。 若修改后不影响项目的构建，正常导入后自动构建便可以成功部署。 当然，若是修改后部署失败，可查看build logs，根据错误信息进行修改。 检查后，在对应项目的settings中，修改对应的构建命令（一般无需修改，但如果添加了额外插件或命令需要，需要根据实际情况进行修改）

3.3 更换个人域名#

在vercel中，默认会分配一个免费的子域名（格式为your-project-name.vercel.app），但也可以绑定自定义域名。若有自己的域名，可以在项目的“Domains”设置中添加自定义域名，并按照提示进行配置。

IMPORTANT

这里配置的自定义域名，实际就是让域名解析到vercel提供的子域名上，从而实现通过自定义域名访问部署的博客站点，所以必须提前有域名否则无法配置。

选择导入项目的settings，在Domains中添加自定义域名，按照提示进行配置（这里填写aliyun.com仅为测试，实际要填自己购买的域名）。 选择好自定义域名后，点击“save”按钮，即可保存配置。 参照提示type及对应的解析目标，添加到域名解析中，一般十分钟内即可生效，点击refresh按钮，即可刷新解析结果，成功后即可直接访问。

4.1 实现markdown自定义指令#

fuwari博客使用的插件默认支持markdown语法，同时也支持自定义指令。自定义指令可以在markdown文件中使用，实现一些特殊的功能，如添加图片、视频、代码块等，通过简单的语法即可实现复杂的现实效果。 一般有三种方式的自定义指令：

1. containerDirective （容器指令）

1
:::tip
2
这是一个提示框
3
:::

2. leafDirective （叶指令）

1
::github{repo="saicaca/fuwari"}

3. textDirective （文本指令）

CAUTION

note:尝试添加自定义指令，如::highlight[需要高亮]{color=“yellow”} ，测试remark-directive插件无法解析，不建议使用，也许插件bug

以leafDirective为例，添加自定义指令::love{name="cpp"} 需要渲染为<div style="color: red;">I love cpp</div> 实现具体步骤如下：

1. 在src/plugins目录下，新建rehype-component-love.mjs文件，添加以下代码

1
mport { h } from "hastscript";
2

3
/**
4
 * Creates a Love component.
5
 *
6
 * @param {Object} properties - The properties of the component.
7
 * @param {string} properties.name - The name to love.
8
 * @param {import('mdast').RootContent[]} children - The children elements of the component.
9
 * @returns {import('mdast').Parent} The created Love component.
10
 */
11
export function LoveComponent(properties, children) {
12
  // console.log("LoveComponent");
13
  if (Array.isArray(children) && children.length !== 0) {
14
    return h("div", { class: "hidden" }, [
15
      'Invalid directive. ("love" directive must be leaf type "::love{name="someone"}")',
16
    ]);
17
  }
18

19
  if (!properties.name) {
20
    return h(
21
      "div",
22
      { class: "hidden" },
23
      'Invalid name. ("name" attribute is required for love directive)',
24
    );
25
  }
26

27
  const name = properties.name;
28
  return h("div", { style: "color: red;" }, `I love ${name}`);
29
}

2. 在astro.config.mjs文件中，添加以下配置

1
import {LoveComponent} from './src/plugins/rehype-component-love.mjs';
2
...
3
    markdown: {
4
        rehypePlugins: [
5
            rehypeComponents,
6
                {
7
                    components: {
8
                        love: LoveComponent,
9
                    },
10
                },
11
        ],
12
    }
13
...

3. 在markdown文件中，使用自定义指令

1
::love{name="cpp"}

效果如下

4.2 为markdown添加mermaid图表支持#

在fuwari博客中，可以通过安装mermaid插件，为markdown文件添加mermaid图表支持。具体步骤如下：

1. 安装mermaid插件 在fuwari项目的根目录下，执行以下命令安装mermaid插件。

1
pnpm add astro-mermaid # 可尝试1.3.1版本

2. 配置mermaid插件 在fuwari项目的astro.config.mjs文件中，添加以下配置，启用mermaid插件。

1
import mermaid from 'astro-mermaid';
2

3
export default defineConfig({
4
  integrations: [
5
    mermaid({              //  客户端渲染
6
      theme: 'base',        // ① 先用 base 主题
7
      themeVariables: {
8
        // ② 全局背景透明
9
        primaryColor: 'transparent',
10
        primaryTextColor: '#e5e7eb',
11
        primaryBorderColor: '#38bdf8',
12
        lineColor: '#38bdf8',
13
        background: 'transparent', // 关键
14
        mainBkg: 'transparent',
15
        secondBkg: 'transparent',
16
        tertiaryColor: 'transparent',
17
      }
18
    },{
19
      startOnLoad: true,
20
      defer: true
21
    }),
22
    .....
23
});

3. 使用mermaid语法 在markdown文件中，可以使用mermaid语法添加图表。例如，以下代码将生成 一个简单的流程图：

1
graph TD;
2
    A-->B;
3
    A-->C;
4
    B-->D;
5
    C-->D;

效果如下

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

其实mermaid显示暂时有问题，设置了全局背景透明，但是图表的背景还是会出现第一次灰色，二次渲染才会正常，待后续有空再研究下