博客使用手册

我的个人学术博客：https://neurpulse.github.io

📖 写作时的注意事项（公式、图片、格式坑）看单独的 写作指南.md

项目	信息
线上地址	https://neurpulse.github.io
代码仓库	https://github.com/NeurPulse/neurpulse.github.io
技术栈	Astro 5（静态网站）+ KaTeX 数学公式 + Shiki 代码高亮
部署方式	推送代码到 GitHub 后自动构建发布（GitHub Actions）
项目目录	E:\selfdocument\web

---

一、日常写作（最常用）

1. 写文章（npm run new 使用教程）

不用手敲 frontmatter，一条命令自动生成：

第 1 步：在 VS Code 里打开本项目文件夹，按 Ctrl + `（Tab 键上面的反引号）打开终端。

第 2 步：运行命令

npm run new

第 3 步：逐项回答（以写一篇 PyTorch 笔记为例，→ 后是你输的内容）

类型  1=学习笔记  2=研究记录  [默认 1]:        → 直接回车（默认笔记）
标题:                                          → 深入浅出PyTorch：自动求导
文件名（英文小写+连字符）:                      → pytorch-autograd
分类:  1=数学建模  2=深度学习  3=深入浅出PyTorch  4=Transformer  5=论文精读  6=未分类
分类序号 [默认 未分类]:                          → 3
标签（逗号分隔，可留空）:                        → PyTorch, autograd
设为精选文章？(y/N):                            → 直接回车（默认不精选）

第 4 步：Typora 会自动打开新文件，frontmatter 和当天日期都已填好。把 ## 小节标题 改成你的第一个小节，开始写正文。

第 5 步：如果用 Typora 编辑过已发布的文章，提交前先跑一次：

npm run fix-images

这会自动把 Typora 改乱的图片路径修回来。然后发布（见下面第 3 节的三条 git 命令）。

小提示：

• 文件名想不出来可直接回车，自动生成（之后重命名文件即可改）
• 标签用中文或英文逗号分隔都行
• 提示"文件已存在"就换个文件名
• 写完不 push 也没关系，文件存在本地，push 了才会上线

手动方式（了解原理，平时不用）：

• 学习笔记 → 在 src/content/notes/ 里新建 .md 文件
• 研究记录 / 论文笔记 → 在 src/content/research/ 里新建 .md 文件

文件名决定网址，建议用英文小写加连字符，例如： src/content/notes/rough-volatility.md → 网址 /notes/rough-volatility/

2. 文件开头必须有的格式（frontmatter）

---
title: '文章标题'
description: '一句话描述（会显示在列表里）'
pubDate: 2026-08-07
order: 12
category: '深度学习'
tags: ['LSTM', '时间序列']
---

正文从这里开始……

字段说明：

字段	必填	说明
title	✅	文章标题
description	建议	列表页显示的简介
pubDate	✅	格式 YYYY-MM-DD，列表按它倒序排列
order	可选	当前分类中的阅读顺序；专题目录和上一篇/下一篇会按它排列
kind	研究内容可选	record 为实际研究记录（默认），template 为写作模板；模板在研究页独立展示，不进入首页精选与最近更新
category	建议	分类，笔记列表页会按它分组，不填默认"未分类"
tags	可选	标签，可以有多个
draft	可选	写 draft: true 表示草稿，不会发布到网站
featured	可选	写 featured: true 表示精选，置顶显示在首页"精选文章"区

参考模板：src/content/research/paper-reading-template.md（论文精读模板；复制后修改文件名、标题和日期，并将 kind: template 改为 kind: record）

3. 发布到网站

在项目目录打开终端（Git Bash），执行：

npm run fix-images   # 修复 Typora 可能改乱的图片路径（用 Typora 编辑过已发文章时必跑）
npm run build        # 确认没有错误（推荐，尤其是加了很多图片时）
git add .
git commit -m "添加文章：文章标题"
git push

等 1~2 分钟自动部署完成，刷新 https://neurpulse.github.io 就能看到。

部署进度可在 Actions 页面查看： https://github.com/NeurPulse/neurpulse.github.io/actions （绿色✓ = 成功；红色✗ = 失败，点进去能看到错误原因）

---

二、本地预览（可选，写长文时有用）

npm run dev

然后浏览器打开 http://localhost:4321 。保存文件后页面自动刷新，适合边写边看效果。按 Ctrl + C 停止。

其他命令：

命令	用途
npm run dev	写作预览（热更新）
npm run build	检查网站能否正常构建（有错会提示）
npm run preview	预览构建后的最终效果
npm install	换电脑/重装后，第一次必须先运行这个

---

三、Markdown 写作技巧

数学公式（KaTeX）

行内公式：$dS_t = \mu S_t dt + \sigma S_t dW_t$

独立公式（单独占一行）：
$$
C = e^{-rT} \, \mathbb{E}\left[ \max(S_T - K, 0) \right]
$$

注意事项：

• 公式里的下划线 _、花括号 {} 直接写，不用转义
• 表格里如果用到 |（竖线），要写成 \|，否则会被当成表格分隔符
• 公式太长时网页上会自动出现横向滚动条，不用担心

代码块

```python
import numpy as np
```

开头 ``` 后面写语言名（python、cpp、matlab、bash 等）就有语法高亮。

插入图片

1. 把图片放进 public/images/ 文件夹（可按文章建子文件夹，如 public/images/deep-learning/）
2. 文章里引用：

![实验结果](/images/my-chart.png)

注意是 /images/ 开头（正斜杠），不要写 public/。

从 Typora 迁移文章时要特别注意图片：

• ❌ C:/Users/... 这样的本地绝对路径——网站上不存在这些文件，必须先把图片复制到 public/images/ 再改引用
• ❌ http:// 开头的外链图片——网站是 https，浏览器会拦截 http 图片。解决办法同上：下载到 public/images/ 本地化
• 图多的话直接找 Claude 帮忙批量处理，一句话的事

---

四、修改个人信息

想改什么	改哪个文件
网站名、作者名、首页研究方向	src/consts.ts
专题导读（适读人群、前置知识、学习目标、阅读路线）	src/data/topics.ts
关于我页面（教育背景、邮箱、GitHub、技能）	src/pages/about/index.astro
项目展示列表	src/data/projects.ts

改完同样执行三条 git 命令发布。

---

五、内置功能说明

以下功能都是全自动的，写文章时无需任何额外操作：

• 文章目录：根据正文里的 ##、###、#### 标题自动生成，桌面显示在文章右侧；手机和平板窄屏显示可折叠的“本文目录”，选择小节后自动收起并跳转，滚动时会高亮当前小节。笔记原有的“专题目录”独立保留；禁用 JavaScript 时仍可展开目录并跳转
• 上一篇/下一篇：文章底部自动按发布时间顺序生成
• 深色模式：右上角太阳/月亮按钮切换，会记住你的选择；首次访问跟随系统设置
• 专题筛选：学习笔记页默认展示专题概览，选择专题后只展开该专题的文章，保留原有阅读顺序。可以直接分享带专题锚点的地址，也支持浏览器前进、后退；禁用 JavaScript 时会显示完整列表
• 全文搜索：导航栏"搜索"页，仅索引学习笔记、研究记录与论文模板的标题、正文，可按专题和类型筛选，论文模板有独立的类型标识；首页、标签汇总页和导航不进入索引。搜索支持中文输入、实时更新与回车提交；关键词和专题/类型可组合筛选、分别清除，并保存在地址中便于刷新或分享。结果按文章展示匹配摘要，每次加载 5 篇；无结果时可清除筛选、更换关键词或浏览专题，加载失败时可重试。注意：本地 npm run dev 时搜索不可用（索引是构建时生成的），用 npm run build && npm run preview 或线上网站测试
• 研究记录与模板：研究页将实际记录和论文模板分开展示；当前只有模板时，记录区显示空状态。两类内容的上一篇/下一篇各自排列，标签页与搜索结果也保留类型标识。npm run new 创建研究内容时自动填入 kind: record
• 项目源码：在 src/data/projects.ts 中仅填写真实的 github 地址；未填写时显示“暂未提供源码链接”，标题保持为文字
• 精选文章：frontmatter 加 featured: true 即显示在首页精选区，description 作为摘要，适合展示最有代表性的笔记
• 首页阅读入口：src/consts.ts 中的研究方向需与笔记分类名称一致，首页会自动显示专题链接和篇数；最近更新按专题各展示一篇，以 updatedDate 或发布日期排序，同日按专题阅读顺序稳定排序

六、目录结构速览

web/
├── src/
│   ├── content/
│   │   ├── notes/         ← 学习笔记放这里（.md）
│   │   └── research/      ← 研究记录放这里（.md）
│   ├── pages/             ← 页面结构（一般不用动）
│   ├── components/        ← 网页组件（不用动）
│   ├── styles/global.css  ← 全站样式（改配色在这）
│   ├── consts.ts          ← 网站名、作者、研究方向
│   └── data/projects.ts   ← 项目列表
├── public/                ← 图片等静态文件
├── astro.config.mjs       ← 网站配置（一般不用动）
└── package.json

---

七、常见问题

Q: 想新增文章分类？ 改 scripts/new-post.mjs 里的 CATEGORIES 数组，加一项即可，立即生效。详见 写作指南.md 第 7 节。

Q: 推送后网站没更新？

1. 去 Actions 页面看是否部署成功（红叉就是失败了）
2. 确认文章的 pubDate 没写成未来日期太远
3. 浏览器强制刷新：Ctrl + Shift + R

Q: 文章发布了但列表里看不到？ 检查 frontmatter 是否完整（尤其是 pubDate），--- 必须顶格写；检查是不是写了 draft: true。

Q: 命令行里 curl 自己网站打不开？ 正常现象。当前网络对 github.io 有限制，命令行不走代理所以打不开，以浏览器为准。

Q: git push 报错 "Custom certificate bundle not found"？ 这台电脑修复过一次：证书在 C:\Users\lichi\certs\ca-bundle.crt。如果重装 Git 后复发，执行：

git config --global http.sslcainfo C:/Users/lichi/certs/ca-bundle.crt

（前提是那个证书文件还在；不在的话从 Git 安装目录 mingw64/etc/ssl/certs/ca-bundle.crt 复制一份过去）

Q: 想绑定自己的域名（如 yourname.com）？ 买域名后在仓库 Settings → Pages → Custom domain 配置，再找 Claude 帮忙即可。

---

本手册由 Claude 生成于 2026-08-07，网站有大的改动时记得更新。