# 用 Prosefly 管理 Astro Content Collections

以 Aster 模板为例，连接 Astro Content Collections，编辑 MDX 文章，审阅 diff，再通过 Git 发布并检查网站更新。

import AsterDemo from '@/components/aster/AsterDemo.astro';

连接已有的 Astro 网站，无需重复定义内容。这篇指南使用我们为作品与写作制作的开源模板 [Aster](https://github.com/prosefly/astro-template-aster)：编辑 **Defaults With an Exit**，审阅后将 MDX 文件发布到你自己的 GitHub 仓库，再检查网站上的同一篇文章。

网站继续使用原有的 Content Collections、文件路径、组件和构建流程。Owner 或 Admin 负责连接仓库、配置发布方式；写作者接入后就能编辑和保存草稿，不需要使用 Git 命令。

## 开始前准备

- 在 GitHub 中创建你自己的 [Aster 副本](https://github.com/prosefly/astro-template-aster)，也可以使用已有的受支持 Astro 项目。你需要有向这个仓库发布内容的权限。
- 创建 Prosefly 账号与组织。Personal 可免费试用一个自然月，无需信用卡；详见[套餐价格](/zh-cn/pricing/)。
- 如果要验证线上更新，先准备好网站原有的构建与托管流程。新建的 Aster 网站需修改 `src/data/config.ts` 中的网站 URL，再按 README 启动和部署。

先浏览 [Aster 示例站](https://astro-template-aster.prosefly.dev/)和[原始文章](https://astro-template-aster.prosefly.dev/blog/defaults-with-an-exit/)。本指南保留示例内容的英文原文，方便对应文章、源码和截图；界面操作不要求你翻译文章。

## 1. 沿用 Aster 已有的内容定义

Aster 的 **Blog** 位于 `src/content/blog/`，**Projects** 位于 `src/content/projects/`。`src/content.config.ts` 已经定义了这些集合的字段：

```ts title="src/content.config.ts"
import { defineCollection, reference } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({
    base: './src/content/blog',
    pattern: '**/*.{md,mdx}',
  }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    publishedAt: z.coerce.date(),
    updatedAt: z.coerce.date().optional(),
    category: z.string(),
    tags: z.array(z.string()).default([]),
    project: reference('projects').optional(),
    draft: z.boolean().default(false),
  }),
});

const projects = defineCollection({
  loader: glob({
    base: './src/content/projects',
    pattern: '**/*.{md,mdx}',
  }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    year: z.number().int(),
    status: z.enum(['Open source', 'Private package']),
    tags: z.array(z.string()).default([]),
    website: z.url().optional(),
    repository: z.url().optional(),
    featured: z.boolean().default(false),
    order: z.number().int().default(0),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog, projects };
```

保留这个文件。Blog 字段包括 `title`、`description`、`publishedAt`、`category`、`tags` 和可选的 `project` 引用。Astro 用这份 schema 校验文件，Prosefly 读取支持的字段，生成文档旁的属性表单。

接入这些集合，无需另写 CMS schema，也无需向 Astro 网站添加 Prosefly 运行时或内容 API。Aster 自身使用 `@prosefly/astro-components` 渲染 MDX 组件；这是模板已有的依赖，与接入 Prosefly 是两件独立的事。

## 2. 连接自己的仓库，确认扫描结果

打开**组织设置 → 仓库**，连接 GitHub 账号，授权 Prosefly GitHub App 访问你的 Aster 仓库，再连接仓库并选择 **Scan repository**。授权画面的详细步骤见[连接 GitHub](/docs/zh-cn/connect-github/)。

检查配置的目标分支和应用根目录，确认识别到了 Blog、Projects 及其原有路径。检查字段与编辑器配置，再确认内容空间并等待索引完成。Aster 的 MDX 导入了 Prosefly 组件，请同时检查这类内容识别到的组件配置。

<p id="aster-scan-demo">
  前往<a href="#try-editor">完整流程</a>体验此步骤。
</p>

扫描只读取仓库，不执行仓库代码，也不修改 Git 文件。若缺少集合，先检查分支、应用根目录和 loader 路径。

## 3. 编辑同一篇文章，保存草稿

打开 **Blog** 集合，选择 **Defaults With an Exit**，对应文件是：

```text
src/content/blog/defaults-with-an-exit.mdx
```

将简介（Description）改成下面的新句子，再在可视化模式中替换开头段落。保留标题、日期、分类、标签和 `project: aster`，让文章继续使用原有的标识和关联。

```diff
-description: Good theme defaults shorten the first week without limiting what the site can become.
+description: Good defaults help a site grow without rewriting its content.
```

```md
A useful theme handles page structure, navigation, search, and readable prose so the team can focus on its content.
```

这些修改只用于你自己的 Aster 副本。切换源码，检查完整的 MDX、frontmatter 与组件导入；编辑时保留已有导入。支持的 Prosefly MDX 组件也能可视化编辑，自定义语法仍可在源码中处理。

<p>
  前往<a href="#try-editor">完整流程</a>体验此步骤。
</p>

等待草稿保存完成。草稿保存在 Prosefly 工作区，保存不会创建 Git commit，也不会更新线上文章。操作说明见[可视化编辑器](/docs/zh-cn/editor/visual-editor/)。

## 4. 审阅并发布这个 MDX 文件

Owner 或 Admin 在**内容空间设置 → 发布**中选择 Commit 或 Pull request。打开发布审阅，逐项确认：

1. 仓库和目标分支是你要发布的位置。
2. 变更文件是 `src/content/blog/defaults-with-an-exit.mdx`。
3. frontmatter 的 diff 包含新简介，正文 diff 包含新的开头段落。
4. 组件导入和其他文章属性仍然完整。

<p id="aster-review-demo">
  前往<a href="#try-editor">完整流程</a>体验此步骤。
</p>

确认后发布。Commit 将审阅过的修改写入配置的目标分支；Pull request 创建提议变更，合并后才会更新目标分支。完整流程见[发布到 Git](/docs/zh-cn/publishing/)。

## 5. Astro 构建后，检查文章页

网站已有的托管流水线会构建更新后的仓库。等待构建完成，再打开**你自己的部署地址**下的 `/blog/defaults-with-an-exit/`。上面的 Aster 示例站用于对照，发布到自己的副本不会修改官方示例站。

检查页面简介与开头段落是否和刚才的修改一致，文章布局和组件能否正常显示，以及文章是否仍关联 Aster 项目。Prosefly 发布内容文件，网站更新由你的 Astro 项目和托管流程完成。

<p id="aster-published-demo">
  前往<a href="#try-editor">完整流程</a>体验此步骤。
</p>

## 体验完整流程

示例从文章编辑开始。使用阶段控件查看仓库连接、内容发现、编辑、审阅和网站预览。

<span id="aster-workflow-demo"></span>

<figure>
  <AsterDemo language="zh-cn" stage="edit" id="try-editor" />
  <figcaption>Aster 交互流程：连接 → 扫描 → 编辑 → 审阅 → 预览网站。</figcaption>
</figure>

## 用在已有的 Astro 项目中

Aster 是示例，并不是使用 Prosefly 的前提。继续使用你自己的网站字段、内容目录和渲染代码。

| 内容结构                                                                 | 使用方式                                                        |
| ------------------------------------------------------------------------ | --------------------------------------------------------------- |
| 静态 Content Collections，使用覆盖整个目录的 Markdown／MDX `glob` loader | 扫描仓库，确认识别出的路径和受支持字段。                        |
| 受支持的静态 schema 字段                                                 | 在文档旁修改属性；发布后的文件继续由 Astro 校验。               |
| 受支持的 MDX 组件配置                                                    | 使用组件的可视化操作，自定义语法在源码中编辑。                  |
| 远程或自定义 loader、动态 schema、选择性文件匹配                         | 检查扫描结果，必要时显式配置内容范围。Prosefly 不执行仓库代码。 |

普通 Astro 内容集合不定义原生文档导航。如果网站使用 Starlight，侧边栏与组件编辑见 [Starlight CMS 接入指南](/docs/zh-cn/frameworks/starlight/)。

## 内容和预期不一致时

| 现象                                 | 检查方法                                                                            |
| ------------------------------------ | ----------------------------------------------------------------------------------- |
| 没有识别到 Blog、Projects 或某个字段 | 检查目标分支、应用根目录、内容路径和支持的 schema 定义，再重新扫描。                |
| MDX 组件在源码中打开                 | 检查识别到的编辑器配置。自定义语法仍可在源码中编辑。                                |
| 网站仍显示旧内容                     | 检查是否只保存了草稿、PR 是否合并、托管构建是否完成，以及是否打开了自己的部署地址。 |
| 在 Prosefly 外修改了 Git 文件        | 重新扫描并建立索引，再继续编辑。                                                    |

接下来查看 [Astro CMS 功能介绍](/zh-cn/frameworks/astro/)、[内容归属](/docs/zh-cn/content-ownership/)，或参考 [Astro Content Collections 官方文档](https://docs.astro.build/en/guides/content-collections/)。