Установка вручную

Самый быстрый способ создать новый сайт на 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 в массив integrations в конфигурационном файле Astro.

Настройка интеграции

Интеграция 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.

Создайте или обновите файл конфигурации контента, добавив коллекцию docs, которая использует схему docsSchema от Starlight:

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 использует маршрутизацию на основе файлов, что означает, что каждый файл Markdown, MDX или Markdoc в src/content/docs/ становится страницей на вашем сайте. Метаданные в начале файла (например, поля title и description в приведённом выше примере) могут изменить отображение страниц.

Посмотрите все доступные параметры в справочнике по метаданным.

Советы для существующих сайтов

Если у вас уже есть существующий проект 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/.

Использование Starlight с SSR

Чтобы включить SSR, следуйте руководству Адаптеры рендеринга по требованию в документации Astro, для добавления серверного адаптера в ваш проект Starlight.

Страницы документации, создаваемые Starlight, по умолчанию предварительно отрисовываются независимо от режима вывода вашего проекта. Для отключения предварительного рендеринга страниц установите для параметра prerender значение false.