feat: init Astro blog with wikilinks, KaTeX and local search

- Astro 5 static blog, zero runtime JS - Obsidian wikilink remark plugin (slug matches Astro content collection) - KaTeX math rendering, local search, TOC, archives, tags - 5 posts on math/physics/ML topics - deploy scripts for nginx + certbot + rsync
2026-08-14 00:19:33 +08:00
commit 12dd13a76f
39 changed files with 19371 additions and 0 deletions
@@ -0,0 +1,107 @@
+# 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
+```