# SuBlog 内容丰富化方案

## 目标

在不显著增加维护成本的前提下，让博客从“文章列表”升级为“有结构的个人知识库”。

核心原则：

- 保持一个主要内容源：`content/posts`
- 优先做自动聚合页面，不新增需要长期手动维护的数据源
- 先增强现有文章，再考虑项目、收藏、短笔记等独立内容类型
- 每个阶段都能独立上线，不做大而全改造

## 当前判断

当前项目已经具备比较完整的博客基础：

- 文章目录结构清晰：`content/posts/<slug>/index.md`
- frontmatter 已支持标题、日期、描述、封面、标签、置顶等字段
- 文章列表页已经有搜索、标签过滤、分页
- 文章详情页已经有目录和评论

因此下一步不建议马上新增 `notes`、`projects`、`bookmarks` 等内容系统。它们看起来丰富，但会引入额外维护负担，时间久了容易荒掉。

更合适的方向是：继续围绕 `posts` 做结构增强。

## 推荐内容模型

继续使用现有文章目录：

```text
content/
└── posts/
    └── <slug>/
        ├── index.md
        └── img/
```

在文章 frontmatter 中增加少量可选字段：

```yaml
title: 文章标题
published: 2026-07-15
updated: 2026-07-15
description: 文章描述
image: /posts/example/img/cover.jpg
tags:
  - Go
  - Docker
pinned: false
series: Nuxt 博客开发
seriesOrder: 1
difficulty: 入门
```

字段说明：

| 字段 | 是否必填 | 用途 |
|------|----------|------|
| `title` | 是 | 文章标题 |
| `published` | 是 | 发布时间 |
| `description` | 是 | 列表页和 SEO 摘要 |
| `tags` | 是 | 标签筛选和内容聚合 |
| `image` | 否 | 封面图 |
| `pinned` | 否 | 首页或列表页置顶 |
| `updated` | 否 | 展示最近更新 |
| `series` | 否 | 归入某个系列 |
| `seriesOrder` | 否 | 系列内排序 |
| `difficulty` | 否 | 标记阅读难度 |

## 目录结构设计

建议新增的页面和工具尽量围绕现有目录展开：

```text
pages/
├── index.vue              # 首页：增加最近文章、精选文章或系列入口
├── posts/
│   ├── index.vue          # 文章列表：保留现有搜索和标签过滤
│   └── [slug].vue         # 文章详情：增加同系列上一篇/下一篇
├── archive.vue            # 归档页：按年月自动聚合文章
└── series/
    ├── index.vue          # 系列列表页
    └── [name].vue         # 系列详情页

utils/
└── content-ast.ts         # 保持现有 AST 工具

composables/
└── usePostSearch.ts       # 保持现有搜索逻辑
```

不建议第一阶段新增：

```text
content/notes/
content/projects/
content/bookmarks/
```

这些目录可以等文章体系稳定后再加。

## 页面能力设计

### 首页

首页保持“个人名片优先”，内容入口作为补充，不要做成文章列表页的重复版本。

当前首页建议顺序：

- 个人身份：头像、站点名、签名、网易云热评、不蒜子计数
- 个人入口：社交链接、常用页面导航、公告、小日历
- 内容入口：文章更新、归档入口、系列入口

视觉重点放在个人主页氛围上。首页头像由 `components/layout/AvatarOrbit.client.vue` 实现，使用 3D 技术栈图标环绕头像，图标需要保持正面朝向，环绕范围只略宽于头像，避免遮挡头像主体。

文章相关模块保持轻量：

- 最近文章：展示最新 3 到 5 篇
- 精选文章：读取 `pinned: true`
- 系列入口：展示有 `series` 的文章分组

不建议增加太多模块，避免首页维护和视觉负担过重。

### 归档页

新增 `/archive` 页面。

数据来源：所有非草稿文章。

展示方式：

- 按年份分组
- 年份下按月份分组
- 每篇文章显示标题、发布日期、标签

维护成本：低。页面完全由文章 frontmatter 自动生成。

### 系列页

新增 `/series` 和 `/series/[name]`。

数据来源：文章 frontmatter 中的 `series` 字段。

展示方式：

- `/series` 展示所有系列名称、文章数量、最近更新时间
- `/series/[name]` 按 `seriesOrder` 或发布时间排序展示文章

文章详情页可以增加：

- 当前系列名称
- 同系列上一篇
- 同系列下一篇

维护成本：中低。只需要在相关文章里填写 `series` 和 `seriesOrder`。

### 文章详情页

建议增强但不改变主体结构：

- 显示 `updated`
- 显示 `difficulty`
- 如果属于系列，显示系列导航

这些信息都来自 frontmatter，不需要额外数据文件。

## 实施阶段

### 第一阶段：低成本增强

目标：快速增加内容层次，但不扩大内容源。

范围：

- 增加 `updated`、`series`、`seriesOrder`、`difficulty` 字段支持
- 首页展示最近文章和置顶文章
- 文章详情页展示更新时间和难度

验收标准：

- 不影响旧文章显示
- 未填写新字段的文章正常展示
- 首页内容入口更明确

### 第二阶段：自动聚合页面

目标：让已有文章自动形成内容结构。

范围：

- 新增 `/archive`
- 新增 `/series`
- 新增 `/series/[name]`
- 文章详情页增加同系列上一篇/下一篇

验收标准：

- 归档页能按年月正确分组
- 系列页能按系列正确聚合
- 系列排序稳定，不受文章读取顺序影响

### 第三阶段：再考虑独立内容类型

目标：在文章体系稳定后，再判断是否值得扩展。

可选方向：

- `projects`：项目展示
- `notes`：短笔记
- `bookmarks`：资源收藏

建议只有在满足以下条件时再做：

- 现有文章更新稳定
- 首页和文章页结构已经成熟
- 确认有长期维护这些内容的需求

## 维护规则

新增文章时只需要遵守一个流程：

1. 使用 `pnpm new-post <slug>` 创建文章
2. 填写必填字段：`title`、`published`、`description`、`tags`
3. 如果文章属于系列，再填写 `series` 和 `seriesOrder`
4. 如果文章有明显更新，再填写或更新 `updated`
5. 如果适合推荐，再设置 `pinned: true`

推荐 frontmatter 模板：

```yaml
---
title: ''
published: 2026-07-15
updated:
description: ''
image:
draft: false
tags: []
pinned: false
series:
seriesOrder:
difficulty:
---
```

## 不做清单

为了控制维护成本，短期不建议做：

- 独立 CMS 后台
- 多内容类型并行维护
- 复杂分类系统
- 手动维护首页推荐配置
- 每篇文章强制填写大量元信息

## 推荐结论

最适合当前项目的方案是：

```text
一个内容源：posts
少量增强字段：series、seriesOrder、updated、difficulty
三个自动视图：首页内容入口、归档页、系列页
```

这样能明显提升内容丰富度，同时不会把项目变成难维护的 CMS。