手动设置

创建新 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: 'My delightful docs site',
    }),
  ],
});

在 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: My docs
description: Learn more about my project in this docs site built with Starlight.
---

Welcome to my project!

Starlight 使用基于文件的路由，这意味着 src/content/docs/ 中的每个 Markdown、MDX 或 Markdoc 文件都会成为你网站上的一个页面。Frontmatter 元数据（即上面示例中的 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。