AstroPaper 主题使用与配置完全指南

本文将 AstroPaper 官方自带的多篇英文文档核心内容合并为了这篇单篇进阶使用指南。您可以在这篇文档里找到添加新文章、定制主题配色、功能扩展等各种技巧。

1. 撰写新博客文章

所有的博客文章都存放在 src/data/blog/ 目录中。AstroPaper 支持嵌套文件夹，比如可以把文章按年份放在 src/data/blog/2026/。

Frontmatter 属性配置

文章头部必须有 Yaml 格式的配置（Frontmatter），否则不会被 Astro 正确解析。如下所示：

---
title: 您的文章标题
author: 您的名字
pubDatetime: 2026-03-15T09:00:00+08:00
slug: your-post-slug # 访问路径，如果不填会默认用文件名
featured: true # 是否在首页 Featured（推荐）区显示
draft: false # 是否为草稿（草稿在生产环境不可见）
tags:
  - 记录
  - 笔记
ogImage: ../../assets/images/example.png # 社交媒体分享大图（可选）
description: 您的文章简介，用于首页截断展示或 SEO 显示。
---

正文中您可以使用常规的 Markdown 语法进行书写。如果您需要加入 目录 (Table of contents)，只需在一级或二级标题中写下 ## Table of contents（或者按您的配置写中文名），渲染器会自动接管将其转换为带跳转链接的完整目录。

2. 定制你的主题颜色方案

AstroPaper 支持亮色（Light）和暗色（Dark）模式，在 src/config.ts 的 lightAndDarkMode 参数中您可以选择开启或者关闭双主题模式。

配色方案在 src/styles/global.css 文件中配置：

@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

/* 默认亮色模式配置 */
:root,
html[data-theme="light"] {
  --background: #fdfdfd; /* 背景色 */
  --foreground: #282728; /* 前景（主要文本）色 */
  --accent: #006cac; /* 强调色（链接悬停效果等） */
  --muted: #e6e6e6; /* 次要颜色（如卡片或引用块背景） */
  --border: #ece9e9; /* 边框色 */
}

/* 默认暗色模式配置 */
html[data-theme="dark"] {
  --background: #212737;
  --foreground: #eaedf3;
  --accent: #ff6b01;
  --muted: #343f60bf;
  --border: #ab4b08;
}

您可以随意修改这里的 CSS Hex 变量值来构建极具个人风格的配色（例如低对比度暗色系或是护眼米黄色）。

OG 图片是用于社媒分享时展示的卡片预览图。AstroPaper 默认集成了 Vercel 的 Satori 工具，以支持在项目打包 (npm run build) 时动态将所有的博客文章转出分享大图。

如果想给某篇文章单独设置分享封面图，可以直接在 Frontmatter 里填写 ogImage。未单独设置时，站点会回退到全局默认分享图。

4. 扩展支持：添加 LaTeX 数学公式支持

Astro 默认不支持数学公式渲染，但是可以通过增加额外的 Rehype/Remark 插件进行增强：

添加依赖：

npm install rehype-katex remark-math katex

在 astro.config.ts 中配置集成：

import remarkMath from "remark-math";
import rehypeKatex from "rehype-katex";

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkMath, remarkToc /* 其他组件 */],
    rehypePlugins: [rehypeKatex],
  }
});

最后在 src/layouts/Layout.astro 的 <head> 下面随便引入一次 Katex 的核心 CSS 样式即可让公式渲染变美观：
```
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css"/>
```

5. 高级：为博客系统增加 Giscus 静态评论

如果您希望读者能够登录 GitHub 后在文章下方留下评论，可以使用基于 GitHub Discussions 的 Giscus：

打开 Giscus 官网并填写你的项目仓库（须设为公开 Public）。
在下方获取它吐出的 <script> 标签块。
打开 src/layouts/PostDetails.astro 文件，在页尾 </main> 区块或底部分享按钮 <ShareLinks /> 组件的下方，粘贴进您的 Giscus 脚本代码，即可直接开启全站评论功能！
（进阶）如果想在切换深色/浅色主题时让评论区无缝切换风格，可以考虑使用 React 封装版的 @giscus/react 包进行渲染。

6. 日常维护 (依赖包更新)

Astro 和诸多生态包版本更新极快，通常建议依靠 npm-check-updates 工具定期将版本升至大版本最高：

npm install -g npm-check-updates
# 检查更新
ncu
# 强制覆盖 package.json 属性
ncu -u

更新后直接重新执行 npm install 下载最新依赖，并 npm run dev 测试项目是否正常即可！