Starlight — полнофункциональная тема для документации на Astro

Starlight — интеграция и набор инструментов на базе Astro для создания сайтов документации. Он добавляет навигацию, поиск, локализацию, SEO-настройки, подсветку кода и готовый интерфейс, сохраняя возможность расширять проект средствами Astro.

Что такое Starlight

Starlight устанавливается как интеграция Astro. Страницы документации можно писать в Markdown, MDX или Markdoc, а файлы из src/content/docs/ преобразуются в маршруты сайта.

Starlight опирается на Astro и поддерживает статическую генерацию, серверный рендеринг через адаптеры и компоненты React, Vue, Svelte или Solid. Страницы Starlight предварительно генерируются по умолчанию, а режим рендеринга по запросу настраивается через SSR-адаптер и параметр prerender.

По состоянию на 8 сентября 2026 года в официальных релизах доступен @astrojs/starlight@0.42.0. Для этой версии требуется Astro 7.2.10 или новее. Starlight и Astro рекомендуется обновлять вместе.

Основные возможности

Создание нового проекта

Самый быстрый вариант — шаблон Starlight:

npm create astro@latest -- --template starlight

Перейдите в созданный каталог и запустите сервер разработки:

cd my-docs
npm run dev

По умолчанию локальный сайт открывается по адресу http://localhost:4321.

Подключение к существующему Astro-проекту

Добавьте интеграцию из корня проекта:

npx astro add starlight

Минимальная конфигурация находится в astro.config.mjs:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Моя документация',
    }),
  ],
});

В актуальной конфигурации Starlight коллекцию документации также нужно определить в 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(), // Загружает Markdown, MDX и Markdoc из src/content/docs/.
    schema: docsSchema(), // Проверяет фронтматтер страниц документации.
  }),
};

docsLoader() загружает локальные файлы Markdown, MDX и Markdoc из src/content/docs/. Файлы, имя которых начинается с подчёркивания, пропускаются.

Добавление страниц

Создайте src/content/docs/index.md:

---
title: Моя документация
description: Инструкции по работе с проектом
---

Добро пожаловать в документацию.

Маршруты формируются из структуры каталогов:

src/content/docs/
├── index.md                → /
├── getting-started.md      → /getting-started/
└── reference/
    └── api.md              → /reference/api/

Фронтматтер управляет заголовком, описанием и другими параметрами страницы. Схема docsSchema() проверяет метаданные при обработке контента, а при необходимости её можно расширить собственными полями.

Основная конфигурация

Параметры Starlight передаются в вызов starlight() внутри astro.config.mjs:

starlight({
  title: 'Моя документация',
  defaultLocale: 'ru', // Локаль для резервного контента.
  locales: {
    ru: { label: 'Русский' },
    en: { label: 'English' },
  },
  sidebar: [
    { slug: 'getting-started' },
    {
      label: 'Справочник',
      items: [
        { autogenerate: { directory: 'reference' } },
      ],
    },
  ],
  social: [
    {
      icon: 'github',
      label: 'GitHub',
      href: 'https://github.com/my/repo',
    },
  ],
  editLink: {
    baseUrl: 'https://github.com/my/repo/edit/main/',
  },
});

Настройка боковой панели

Без свойства sidebar Starlight строит навигацию по содержимому src/content/docs/ и использует заголовки страниц как подписи.

Для ручной навигации укажите внутренние страницы через slug, а внешние или произвольные маршруты через link:

sidebar: [
  { slug: 'intro' },
  { slug: 'installation' },
  { label: 'NASA', link: 'https://www.nasa.gov/' },
]

Автогенерируемый каталог можно поместить в группу:

sidebar: [
  {
    label: 'Руководства',
    items: [
      { autogenerate: { directory: 'guides' } },
    ],
  },
]

Положение и вид автоматически созданной ссылки настраиваются во фронтматтере страницы:

---
title: Моя страница
sidebar:
  label: Кастомная метка
  order: 2
  badge:
    text: Новое
    variant: tip
---

Группы сворачиваются по умолчанию с помощью collapsed: true. Для автоматически созданных вложенных групп используется autogenerate.collapsed.

Интернационализация

Ключи объекта locales соответствуют каталогам внутри src/content/docs/:

src/content/docs/
├── en/
│   └── getting-started.md
├── ru/
│   └── getting-started.md
└── ar/
    └── getting-started.md

Для языков с письмом справа налево задайте dir: 'rtl'. Если перевода страницы нет, Starlight может использовать контент defaultLocale.

Одноязычный русский сайт без префикса /ru/ настраивается через корневую локаль:

locales: {
  root: {
    label: 'Русский',
    lang: 'ru',
  },
}

Для собственных переводов интерфейса настройте коллекцию i18n через i18nLoader() и i18nSchema(). Она загружает JSON- и YAML-файлы из src/content/i18n/.

Поиск Pagefind и серверный рендеринг

Pagefind включён по умолчанию и индексирует предварительно сгенерированный сайт. Его можно настроить объектом pagefind или отключить значением false.

Starlight предварительно генерирует свои страницы даже в Astro-проекте с серверным режимом. Для рендеринга по запросу добавьте подходящий Astro-адаптер и установите prerender: false. При использовании Cloudflare официальное руководство также требует флаг совместимости nodejs_compat в конфигурации Wrangler.

Компоненты и оформление

В MDX доступны компоненты Starlight: карточки, сетки карточек, вкладки, блоки-примечания, значки, иконки, кнопки, пошаговые инструкции и дерево файлов. Можно подключать собственные Astro-компоненты и компоненты поддерживаемых UI-фреймворков.

Для изменения стилей добавьте CSS-файл:

/* src/styles/custom.css */
:root {
  --sl-font: 'IBM Plex Serif', serif;
}

Подключите его в конфигурации:

customCss: ['./src/styles/custom.css']

Логотип задаётся через logo; разрешены единый файл или отдельные изображения для светлой и тёмной темы. Более глубокая настройка выполняется через components, где стандартный компонент заменяется файлом из проекта.

Полезные сценарии

Документация библиотеки или API

Задача: хранить документацию рядом с кодом и поддерживать её через Git.

Условие: есть Astro-проект и набор страниц, которые нужно собрать в справочный сайт.

Действие: добавьте Starlight, разложите страницы по src/content/docs/ и настройте editLink на репозиторий.

Результат: после запуска маршруты соответствуют структуре файлов, а боковая панель содержит созданные страницы.

Ограничение: если страницы должны рендериться по запросу, учтите несовместимость стандартного Pagefind с prerender: false.

Раздел документации внутри существующего сайта

Задача: добавить документацию в уже работающий Astro-проект.

Условие: основной сайт уже настроен, а документация должна начинаться с /guides/.

Действие: установите интеграцию и поместите материалы, например, в src/content/docs/guides/.

Результат: страницы из этого каталога доступны под /guides/.

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

Многоязычная база знаний

Задача: поддерживать несколько языковых версий документации.

Условие: для каждой локали подготовлены каталоги контента и настроен объект locales.

Действие: укажите defaultLocale, проверьте локализованные маршруты и поведение страницы без перевода. Для собственных строк интерфейса добавьте коллекцию i18n.

Результат: переключатель языка и страницы локалей работают по заданной конфигурации, а отсутствующий перевод может заменяться контентом defaultLocale.

Ограничение: резервный контент помогает показать страницу, но сам по себе не означает, что перевод подготовлен.

Закрытая документация с авторизацией

Задача: отдавать часть документации только после проверки доступа.

Условие: Astro-проект работает с SSR-адаптером.

Действие: настройте механизм авторизации проекта и установите prerender: false для страниц, которые должны рендериться по запросу.

Результат: выбранные страницы обрабатываются сервером по запросу.

Ограничение: стандартный Pagefind при prerender: false недоступен, поэтому поиск потребуется заменить или отключить.

Проверка результата

Примеры в этом материале сверены с официальной документацией и релизом Starlight; запуск проекта в рамках подготовки не выполнялся.

После настройки выполните следующие действия:

1. Запустите npm run dev.
2. Откройте главную страницу и один вложенный маршрут из src/content/docs/.
3. Проверьте наличие страниц в боковой панели.
4. Если настроены локали, откройте маршруты каждого языка и страницу без перевода.
5. Если используется стандартный поиск, убедитесь, что prerender не установлен в false.
6. Перед обновлением изучите примечания к выбранному релизу, особенно если проект переопределяет компоненты или CSS Starlight.

Обновление Starlight

Обновляйте Astro и Starlight одной командой:

npx @astrojs/upgrade

Для Starlight 0.42.0 минимальная версия Astro — 7.2.10. Перед обновлением проекта с собственными стилями, темой или заменёнными компонентами проверьте описание релиза.

Лицензия и эксплуатационные расходы

В проверенных официальных источниках нет достаточных данных, чтобы подтвердить лицензию Starlight, тарифы или лимиты. Перед внедрением проекта эти параметры нужно сверить по актуальному репозиторию и документации.

Когда Starlight подходит

Starlight удобен для справочников, документации продукта, API и внутренних баз знаний, особенно если контент хранится в Git и собирается вместе с Astro-проектом.

Для блога, магазина или произвольного продуктового интерфейса Astro обычно даёт более подходящую основу. Starlight можно разместить внутри существующего проекта как отдельный раздел документации.

Официальные ссылки

• Сайт и документация Starlight
• Ручное подключение к Astro-проекту
• Настройка боковой панели
• Справочник конфигурации
• Релизы на GitHub
• Репозиторий Starlight

Следующий шаг

База знаний: Astro: фреймворк для молниеносных сайтов

Для выбора Starlight полезно отдельно обсудить структуру документации и границы интеграции с Astro. Это особенно актуально для команд, которые собирают справочный раздел внутри действующего сайта.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov