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

Самый быстрый способ создать новый сайт на 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/:

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryguides/

        • guide.md
        • index.md
  • Directorypages/

    • …
• astro.config.mjs

В будущем мы планируем улучшить такой вариант использования путей, чтобы избежать необходимости в лишнем вложенном каталоге в src/content/docs/.

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

На данный момент Starlight не поддерживает развертывание с SSR через серверные адаптеры Astro. Мы надеемся, что сможем реализовать это в ближайшем будущем.