yukun-hh
12dd13a76f
- 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
107 lines
3.3 KiB
Markdown
107 lines
3.3 KiB
Markdown
# 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
|
||
```
|