108 lines
3.3 KiB
Markdown
108 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
|
|||
|
|
```
|