# 为 Starlight 文档站接入 CMS

将 Starlight 接入 Prosefly，编辑页面属性和支持的文档组件，并审阅手动侧边栏与自动分组的导航变更。

import StarlightDemo from '@/components/starlight/StarlightDemo.astro';

为已有的 Starlight 文档站接入可视化 CMS，让团队直接更新指南。管理员负责连接仓库和配置发布方式，作者可以编辑文档、页面属性和支持的组件，不需要学习 Git 命令。

网站继续使用原有的 Starlight 主题、URL 和构建流程。本指南从扫描已有仓库开始，完成一次包含内容与导航的发布。

## 1. 检查 docs 集合

仓库中应包含使用 Starlight 的 Astro 应用及其文档文件。标准 docs 集合使用 Starlight 的 loader 和 schema：

```ts title="src/content.config.ts"
import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};
```

如果项目已经有这份配置，保留即可。支持的静态 schema 扩展可以增加或覆盖字段；Prosefly 读取这些定义，不运行网站应用。

## 2. 连接仓库、扫描并确认导航

打开**组织设置 → 仓库**，连接 GitHub 仓库，再选择 **扫描仓库**。账号连接与 GitHub App 授权的步骤见[连接 GitHub](/docs/zh-cn/connect-github/)。

检查识别到的 Starlight 应用、文档目录、集合属性、编辑器配置和原生导航配置。确认内容空间及受支持的导航绑定，等待索引建立完成。

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

## 3. 编辑指南与页面属性

从 **内容** 打开一篇指南。可视化编辑器支持 Markdown，以及提示块、标签页、卡片和文件树等受支持的 Starlight 组件。在 **属性** 中修改 标题、简介 等字段；其他支持的字段可以在 更多属性 中找到。

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

自定义组件或没有可视化控件的表达式，可以切换到 源码模式编辑。也可以先打开 [Starlight 编辑器示例](/zh-cn/frameworks/starlight/#try-editor)尝试组件操作；在线体验无需注册，刷新后会重置内容。

## 4. 调整手动条目与自动分组

在属性和大纲旁打开 **导航**。受支持的静态 Starlight 侧边栏可以同时包含手动条目和自动目录，例如已有 `starlight()` 配置中的这段内容：

```js
sidebar: [
  { label: 'Start Here', items: ['overview'] },
  { label: 'Guides', autogenerate: { directory: 'guides' } },
];
```

- **手动分组：**在已有的可写分组中调整支持的条目，或为尚未列入导航的页面选择受支持的位置。
- **自动分组：**页面来自 `autogenerate.directory` 指定的目录。拖动同一目录内的已有页面排序时，Prosefly 会更新它们的 `sidebar.order` frontmatter。

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

自动分组排序不会移动 Markdown 文件。打开审阅前，等待导航面板的保存状态显示完成。此时变更仍是草稿，还没有写入 Git。

## 5. 审阅受影响的文件并发布

打开发布审阅，逐个检查变更文件。手动侧边栏调整可能修改 `astro.config.mjs`；自动页面排序可能修改文档 frontmatter 中的 `sidebar.order`。将这些变更与正文一起审阅。

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

按内容空间配置的 Commit 或 Pull request 模式发布。使用 PR 时，需要先合并到目标分支，再由原有 Starlight 构建流程呈现并部署网站。构建完成后，检查页面和侧边栏是否符合预期。

如果配置无法提供可写的原生导航绑定，可以在适用时选择仅发布内容；这种方式不会把页面加入侧边栏。相关操作见[网站导航](/docs/zh-cn/repositories-and-spaces/)和[发布到 Git](/docs/zh-cn/publishing/)。

## 6. 继续使用原来的 Starlight 网站。

内容发布到 Git 后，原有的 Astro 构建流程生成并部署网站。Pull request 需要先合并。下方完整流程中的网站步骤展示了 Starlight 网站示例。

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

## 体验完整流程

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

<figure>
  <StarlightDemo language="zh-cn" stage="edit" id="try-editor" />
  <figcaption>Starlight 完整流程：连接 → 扫描 → 编辑 → 导航 → 审阅 → 网站。</figcaption>
</figure>

## 检查第一次更新

确认页面标题、正文、侧边栏位置和自动分组顺序。以后在 Prosefly 之外修改配置或文件时，先重新扫描并更新索引，再继续编辑。

继续查看 [Starlight CMS 功能介绍](/zh-cn/frameworks/starlight/)、[产品文档使用场景](/zh-cn/use-cases/documentation/)、[MDX 组件使用指南](/docs/zh-cn/editor/)，或参考 [Starlight 内容编写文档](https://starlight.astro.build/guides/authoring-content/)。