主题自定义配置笔记

本文档持续记录 AstroPaper 主题的各种自定义配置位置和修改方法。

⚡ 通用修改步骤

1. 定位对应的配置文件
2. 找到需要修改的代码或配置项
3. 进行修改并保存文件
4. 开发服务器会自动热重载，实时预览效果

提示：修改后记得在明暗两种主题下都进行测试，确保视觉效果一致。

🎨 背景颜色修改

📁 主要文件位置

src/styles/global.css

颜色变量定义

浅色主题（默认）

:root,
html[data-theme="light"] {
  --background: #fdfdfd; /* ← 修改此处 */
}

深色主题

html[data-theme="dark"] {
  --background: #212737; /* ← 修改此处 */
}

🔗 导航菜单激活状态样式

📁 样式定义位置

src/styles/global.css

推荐样式配置

.active-nav {
  @apply text-accent underline decoration-solid decoration-1 underline-offset-8;
}

样式参数说明

• text-accent：文字变为强调色（自动适配明暗主题）
  • 浅色主题：蓝色 #006cac
  • 深色主题：橙色 #ff6b01
• decoration-solid：直线样式（替代原来的波浪线）
• decoration-1：1px 粗细的细线
• underline-offset-8：8px 间距，提供良好的视觉呼吸感

应用方式

当导航菜单项处于激活状态时，会自动应用 .active-nav 类，显示文字颜色变化 + 细直线下划线效果。

自定义调整建议

如果需要微调下划线间距，可以修改 underline-offset 值：

• underline-offset-3：紧凑型间距
• underline-offset-5：中等间距
• underline-offset-8：宽松间距（当前推荐）

📱 Social Links 配置（首页）

📁 配置文件位置

src/constants.ts

配置对象

export const SOCIALS: Social[] = [
  {
    name: "GitHub",
    href: "https://github.com/MaizeDev/my-blog-maize",
    linkTitle: `${SITE.title} on GitHub`,
    icon: IconGitHub,
  },
  {
    name: "X", 
    href: "https://x.com/username",
    linkTitle: `${SITE.title} on X`,
    icon: IconBrandX,
  },
  // ... 其他社交链接
] as const;

可用图标

• IconMail、IconGitHub、IconBrandX、IconLinkedin
• IconWhatsapp、IconFacebook、IconTelegram、IconPinterest

修改方法

• 添加链接：在 SOCIALS 数组中添加新对象
• 删除链接：从数组中移除对应对象或注释掉
• 修改链接：更改 href 和 linkTitle 的值
• 更换图标：使用不同的图标组件（需确保已导入）

显示逻辑

首页会自动检测 SOCIALS.length > 0，如果数组为空则不显示 “Social Links:” 区域。

🌐 分享链接新窗口打开

📁 问题描述

默认情况下，文章页面的分享链接会在当前窗口跳转到分享网站，影响用户浏览体验。

📁 配置文件位置

src/components/ShareLinks.astro

🔧 解决方案

修改 LinkButton 组件，添加 target="_blank" 和 rel="noopener noreferrer" 属性：

<LinkButton
  href={`${social.href + URL}`}
  target="_blank"
  rel="noopener noreferrer"
  class="scale-90 p-2 hover:rotate-6 sm:p-1"
  title={social.linkTitle}
>
  <social.icon class="inline-block size-6 scale-125 fill-transparent stroke-current stroke-2 opacity-90 group-hover:fill-transparent sm:scale-110" />
  <span class="sr-only">{social.linkTitle}</span>
</LinkButton>

📝 属性说明

• target="_blank"：在新窗口/标签页中打开链接
• rel="noopener"：防止新页面通过 window.opener 控制原页面，提升安全性
• rel="noreferrer"：防止发送 Referer 头，保护用户隐私

💡 效果

修改后，所有分享链接（Facebook、X/Twitter、WhatsApp、Telegram、Pinterest、邮件等）都会在新窗口中打开，不会中断用户当前的博客浏览体验。

☁️ Cloudflare Pages 构建问题排查与解决

📁 问题背景

在使用 Obsidian + Templater 插件创建博客文章模板后，提交到仓库并通过 Cloudflare Pages 构建时遇到两个关键错误，导致构建失败。

❌ 错误一：InvalidContentEntryDataError（日期格式错误）

🔍 错误日志

[InvalidContentEntryDataError] blog → slug data does not match collection schema.
pubDatetime: Expected type "date", received "string"
modDatetime: Expected type "date", received "string"
Location: /opt/buildhome/repo/src/data/blog/_templates/blog-post-template.md:0:0

🧠 根本原因

1. 模板文件被误处理：Astro 内容集合系统尝试解析 _templates/ 目录下的模板文件
2. 占位符格式问题：模板中的 {{date}}T{{time}}Z 是字符串占位符，不是有效的日期对象
3. Schema 验证失败：内容集合 schema 要求 pubDatetime 和 modDatetime 必须是 z.date() 类型

🔧 解决方案

更新内容集合配置，明确排除模板目录：

📁 文件位置：src/content.config.ts

const blog = defineCollection({
  loader: glob({ 
    pattern: ["**/[^_]*.md", "!_templates/**"], // ← 添加排除规则
    base: `./${BLOG_PATH}` 
  }),
  // ... 其他配置
});

💡 最佳实践建议

• 模板目录命名：始终使用 _ 开头的目录名（如 _templates）存放模板文件
• 显式排除：在 glob 模式中明确添加排除规则 !_templates/**
• Obsidian Templater 配置：确保日期输出为 ISO 8601 格式：

  pubDatetime: <%* tp.date.now("YYYY-MM-DDTHH:mm:ss") + "Z" %>
  ```

❌ 错误二：ImageNotFound（图片路径错误）

🔍 错误日志

[ImageNotFound] Could not find requested image `../../assets/images/forrest-gump-quote.png`
Location: /opt/buildhome/repo/src/data/blog/_releases/how-to-update-dependencies.md

🧠 根本原因

相对路径层级计算错误：

• 文件位置：src/data/blog/_releases/how-to-update-dependencies.md
• 错误路径：../../assets/images/forrest-gump-quote.png（只回退了2级）
• 正确路径：../../../assets/images/forrest-gump-quote.png（需要回退3级）

🔧 解决方案

修正相对路径层级：

📁 文件位置：src/data/blog/_releases/how-to-update-dependencies.md

# 修正前（错误）
ogImage: ../../assets/images/forrest-gump-quote.png

# 修正后（正确）
ogImage: ../../../assets/images/forrest-gump-quote.png

💡 路径计算规则

🚀 更优解决方案建议

考虑使用 Astro 的 @/ 别名路径（如果配置支持）：

ogImage: @/assets/images/forrest-gump-quote.png
```
这样可以避免手动计算相对路径层级的复杂性。

### 🧹 构建产物清理规范

#### 🔧 清理命令
```
# 删除构建产物
rm -rf dist

# 删除搜索索引
rm -rf public/pagefind
```

#### 📋 清理时机
- 提交代码前
- 重新构建前  
- 部署失败后排查问题时

#### 📁 版本控制
确保 `.gitignore` 中包含以下条目：
```
dist/
public/pagefind/
.astro/
```

### ✅ 验证步骤
1. **本地构建测试**：运行 `pnpm run build` 确保无错误
2. **清理构建产物**：删除 `dist/` 和 `public/pagefind/`
3. **提交代码**：推送修复后的代码到仓库
4. **云端验证**：观察 Cloudflare Pages 构建日志确认成功

### 📝 经验总结
1. **内容集合隔离**：模板文件、归档文件必须与实际博客文章物理隔离
2. **路径精确计算**：相对路径必须严格计算目录层级深度
3. **本地先行验证**：重要修改先在本地构建验证，再提交到云端
4. **错误日志分析**：仔细阅读构建日志，定位具体文件和行号

## 📁 内容集合配置优化（排除主题自带文档）

### 📌 问题背景
`_examples` 和 `_releases` 目录包含 AstroPaper 主题自带的示例文章和发布说明文档。这些文件：
- 不需要在博客中展示
- 可能包含不符合当前 schema 的字段
- 会增加不必要的构建处理时间

### 🔧 解决方案
**更新内容集合 glob 模式，明确排除所有主题自带目录：**

📁 文件位置：[src/content.config.ts](https://github.com/MaizeDev/my-blog-maize/tree/main/src/content.config.ts)

```
const blog = defineCollection({
  loader: glob({ 
    pattern: [
      "**/[^_]*.md",     // 匹配所有不以 _ 开头的 Markdown 文件
      "!_templates/**",   // 排除模板目录
      "!_examples/**",    // 排除示例文章目录  
      "!_releases/**"     // 排除发布说明目录
    ],
    base: `./${BLOG_PATH}` 
  }),
  // ... 其他配置
});
```

### 💡 优势说明
- **构建性能提升**：减少不必要的文件处理
- **错误预防**：避免主题自带文档的 schema 不兼容问题
- **内容纯净**：确保博客只显示用户原创内容
- **维护简便**：无需手动删除或隐藏主题自带文件

### 📋 目录用途说明
| 目录 | 用途 | 是否排除 | 原因 |
|------|------|----------|------|
| `_templates` | Obsidian 博客模板 | ✅ 是 | 防止模板占位符导致构建错误 |
| `_examples` | 主题示例文章 | ✅ 是 | 主题自带，无需展示 |
| `_releases` | 主题发布说明 | ✅ 是 | 主题自带文档，无需展示 |
| （根目录） | 用户原创文章 | ❌ 否 | 实际博客内容 |

### 🚀 最佳实践建议
- **保留但排除**：不要删除主题自带文件，便于参考和更新
- **统一管理**：所有非用户内容都使用 `_` 前缀并统一排除
- **定期检查**：主题更新后检查是否有新的归档目录需要排除