# Yukun's Blog

一个基于 [Astro](https://astro.build) 5 的静态博客。液态玻璃质感、淡蓝配色、零运行时 JS，支持 KaTeX 公式、Obsidian wikilink、本地搜索、文章目录与归档时间轴。

## 环境要求

- Node.js ≥ 20.3（建议 20 或 22 LTS）
- npm ≥ 10

## 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 本地开发（http://localhost:4321）
npm run dev

# 3. 生产构建（输出到 dist/）
npm run build

# 4. 本地预览构建产物
npm run preview

# 5. 类型检查
npm run check
```

## 写作

文章放在 `src/content/posts/` 下，格式为 Markdown（`.md`）。frontmatter 字段：

```yaml
---
title: "文章标题"
date: 2026-08-13          # 必填，发布日期
updatedDate: 2026-08-14   # 可选，更新日期
description: "摘要"        # 可选
tags: ["数学", "AI"]      # 可选
draft: false              # true 时本地可见、构建不发布
pinned: false             # true 时首页置顶大卡片
heroGradient: ["#7fb8ff", "#2f8df0"]  # 可选，封面渐变色
---
```

### Obsidian wikilink

正文支持 Obsidian 风格的双链语法（由 `src/remark-wikilinks.mjs` 处理）：

```markdown
[[#页内锚点]]
[[笔记名]]               → /posts/笔记名
[[笔记名#锚点]]          → /posts/笔记名#锚点
[[笔记名|显示文字]]      → 自定义显示文字
```

> ⚠️ **重要**：Astro 内容集合会用 github-slugger 生成 URL（ASCII 大写自动转小写），
> 例如 `变分下界ELBO笔记.md` 的实际路径是 `/posts/变分下界elbo笔记`。
> 链接指向的**标题必须与文章内实际标题完全一致**，且**页内锚点必须指向真实存在的标题**（加粗段落不是标题，不会被生成锚点）。

### 数学公式

支持 `$...$` 行内公式与 `$$...$$` 块级公式，使用 KaTeX 渲染。

## 目录结构

```
├── astro.config.mjs          # 构建配置（remark/rehype 插件、site）
├── deploy/                   # 服务器部署脚本（nginx + rsync + certbot）
├── public/                   # 静态资源
└── src/
    ├── components/           # UI 组件（导航、卡片、目录、搜索弹窗等）
    ├── content/posts/        # 文章（Markdown 源）
    ├── layouts/              # 页面布局
    ├── lib/utils.ts          # 文章读取、格式化、阅读时间等工具
    ├── pages/                # 页面路由（首页、文章列表、归档、标签、关于）
    ├── remark-wikilinks.mjs  # Obsidian wikilink 转换插件
    └── styles/               # 全局样式
```

## 部署到服务器

`deploy/` 目录提供一键部署脚本（构建 → rsync → reload nginx）：

```bash
# 首次部署（上传 nginx 配置）
./deploy/deploy.sh setup-nginx

# 申请 HTTPS 证书
./deploy/deploy.sh certbot

# 以后每次发布
./deploy/deploy.sh
```

部署脚本的服务器信息（SSH 用户、域名、站点目录）在 `deploy/deploy.sh` 顶部「配置区」中修改。

## 常见问题

**改了 `remark-wikilinks.mjs` 或 Markdown 渲染逻辑后构建没生效？**

Astro 5 会把内容渲染结果缓存在 `node_modules/.astro/data-store.json`，修改渲染插件后需先删除缓存再构建：

```bash
rm -rf node_modules/.astro
npm run build
```