跳转到内容

手动配置

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

设置 Starlight

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

添加 Starlight 集成

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

Terminal window
npx 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 的 docsSchemadocs 集合:

src/content/config.ts
import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ schema: docsSchema() }),
};

添加内容

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

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

src/content/docs/index.md
---
title: 我的文档
description: 通过 Starlight 构建的文档网站,了解有关我的项目的更多信息。
---
欢迎来到我的项目!

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

现有站点的提示

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

在子路径中使用 Starlight

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

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

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • Directoryguides/
          • guide.md
          • index.md
    • Directorypages/
  • astro.config.mjs

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

结合 SSR 使用 Starlight

目前,Starlight 不支持使用 Astro 的服务器适配器进行 SSR 部署 。我们希望能够尽快支持这一点。