Yukun's Blog

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

环境要求

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

快速开始

# 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 字段：

---
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 处理）：

[[#页内锚点]]
[[笔记名]]               → /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）：

# 首次部署（上传 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，修改渲染插件后需先删除缓存再构建：

rm -rf node_modules/.astro
npm run build