手动配置

创建新的 Starlight 站点的最快方法是使用 create astro，如入门指南所示。 如果你想将 Starlight 添加到现有的 Astro 项目中，本指南将解释如何操作。

设置 Starlight

要遵循本指南，你需要一个现有的 Astro 项目。

添加 Starlight 集成

Starlight 是一个 Astro 集成。通过在项目的根目录中运行 astro add 命令将其添加到你的站点中：

npm

npx astro add starlight

pnpm

pnpm astro add starlight

Yarn

yarn astro add starlight

这将安装所需的依赖项，并将 Starlight 添加到 Astro 配置文件中的 integrations 数组中。

配置集成

Starlight 集成在 astro.config.mjs 文件中配置。

添加一个 title 以开始：

astro.config.mjs

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: '我的令人愉悦的文档网站',
    }),
  ],
});

在 Starlight 配置参考 中查找所有可用选项。

配置内容集合

Starlight 是建立在 Astro 的内容集合之上的，这些集合在 src/content.config.ts 文件中配置。

创建或更新内容配置文件，添加一个使用 Starlight 的 docsLoader 和 docsSchema 的 docs 集合：

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() }),
};

Starlight 也支持 legacy.collections 标志，其中集合使用旧版的内容集合实现处理。 这对于你有一个现有的 Astro 项目，目前无法对集合进行任何更改以使用加载器的情况非常有用。

添加内容

现在 Starlight 已经配置好了，是时候添加一些内容了！

创建一个 src/content/docs/ 目录，并从添加一个 index.md 文件开始。 这将是你的新站点的首页：

src/content/docs/index.md

---
title: 我的文档
description: 通过 Starlight 构建的文档网站，了解有关我的项目的更多信息。
---

欢迎来到我的项目！

Starlight 使用基于文件的路由，这意味着 src/content/docs/ 中的每个 Markdown、MDX 或 Markdoc 文件都将变成你站点上的一个页面。前置元数据（上面示例中的 title 和 description 字段）可以更改每个页面的显示方式。在 frontmatter 指南 中查看所有可用选项。

现有站点的提示

如果你有一个现有的 Astro 项目，你可以使用 Starlight 快速地为你的站点添加一个文档部分。

在子路径中使用 Starlight

要在子路径中添加所有 Starlight 页面，请将所有文档内容放在 src/content/docs/ 的子目录中。

例如，如果 Starlight 页面都应该以 /guides/ 开头，请将内容添加到 src/content/docs/guides/ 目录中：

• 文件夹src/

  • 文件夹content/

    • 文件夹docs/

      • 文件夹guides/

        • guide.md
        • index.md
  • 文件夹pages/

    • …
• astro.config.mjs

在将来，我们计划更好地支持这种用例，以避免在 src/content/docs/ 中需要额外的嵌套目录。

结合 SSR 使用 Starlight

要启用 SSR，请按照 Astro 文档中的 “按需渲染适配器” 指南将服务器适配器添加到你的 Starlight 项目中。

无论项目的输出模式如何，Starlight 生成的文档页面都默认为预渲染。要选择不对 Starlight 页面进行预渲染，请将 prerender 配置选项 设置为 false。