个人博客

基于 Astro 6 + Tailwind CSS v4 + TypeScript 构建的静态个人博客。

---

特点

深色模式

一键切换浅色 / 深色主题，无闪烁，偏好持久化。

友链卡片

卡片式友链展示，支持头像、名称、描述，无头像时自动生成渐变占位图。

数学公式

基于 KaTeX 服务端渲染，支持行内和块状两种形式，零客户端 JS。

Mermaid 绘图

在 Markdown 代码块中直接编写 Mermaid 图表，构建时由 rehype-mermaid 渲染为 SVG，自动适配深色 / 浅色主题。

其它功能

• Markdown / MDX 写作，Shiki 代码高亮（双主题）
• 文章目录，滚动时自动高亮当前章节
• 标签筛选，无刷新切换
• Gitalk 评论（基于 GitHub Issues）
• View Transitions 页面切换动画

---

开发

npm install
npm run dev      # 开发服务器，默认 http://localhost:4321
npm run build    # 构建生产版本
npm run preview  # 本地预览构建产物

---

写作

在 src/content/posts/ 下新建 .mdx 或 .md 文件，文件名即 URL slug。

---
title: "文章标题"
date: 2024-06-01
tags: ["标签A", "标签B"]
excerpt: "显示在卡片上的摘要"
cover: "/images/cover.jpg"  # 可选
draft: false                # true 则不出现在列表
sider: "content"            # content=目录 | bar=侧边栏 | 不填=居中无侧边
---

数学公式（MDX 文件中导入使用）

import Math from '@/components/ui/Math';

行内：<Math formula="E = mc^2" />
块状：<Math block formula="\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}" />

Mermaid 图表（直接用代码块，无需导入）

```mermaid
flowchart LR
  A --> B --> C
```

---

部署到 GitHub Pages

1. 修改站点配置

编辑 src/config/site.ts 和 astro.config.mjs，将 site / url 改为你的实际地址：

// src/config/site.ts
export const SITE = {
  title: '你的博客名',
  url: 'https://<用户名>.github.io',
};

// astro.config.mjs
export default defineConfig({
  site: 'https://<用户名>.github.io',
});

如果使用普通仓库名（如 blog）而非 <用户名>.github.io，还需在 astro.config.mjs 中设置 base: '/blog'。

2. 启用 GitHub Pages

进入仓库 Settings → Pages，将 Source 设置为 GitHub Actions。

3. 推送代码

git init
git remote add origin https://github.com/<用户名>/<仓库名>.git
git add .
git commit -m "init"
git push -u origin main

推送后 GitHub Actions 自动构建并部署，约 2 分钟后生效，后续每次推送均自动触发。

4. 配置 Gitalk 评论（可选）

在 GitHub 创建 OAuth App，回调地址填写博客域名，然后编辑 src/config/site.ts：

export const GITALK_CONFIG = {
  clientID: 'your_client_id',
  clientSecret: 'your_client_secret',
  repo: '<仓库名>',
  owner: '<用户名>',
  admin: ['<用户名>'],
};

---

新增页面

方式一：Markdown 内容页

1. 在 src/content/pages/ 新建 .mdx 文件
2. 在 src/pages/ 创建对应路由文件（参考 about.astro）
3. 在 src/config/site.ts 的 NAV_LINKS 中添加导航项

方式二：自定义 Astro 页面

直接在 src/pages/ 创建 .astro 文件，使用 SidebarLayout 或 BaseLayout 布局，然后在 NAV_LINKS 中添加导航项。

---

项目结构

src/
├── components/
│   ├── layout/     # BaseHead、Header、Footer
│   ├── post/       # PostCard、目录、评论
│   ├── sidebar/    # ProfileCard、TagCloud、RecentComments
│   └── ui/         # ThemeToggle、TagBadge、LinkCard、Math
├── content/
│   ├── posts/      # 博客文章（.mdx / .md）
│   └── pages/      # 独立页面内容（about 等）
├── layouts/        # BaseLayout、SidebarLayout、PostLayout
├── pages/          # 路由页面
├── styles/         # global.css、prose.css
├── utils/          # posts.ts、toc.ts、reading-time.ts
└── config/
    └── site.ts     # 站点信息、导航、Gitalk 配置