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

Starlight — готовая тема для Astro, которая превращает набор Markdown-файлов в полноценный сайт документации с навигацией, поиском, i18n и тёмной темой из коробки.

Что это такое

Starlight — open-source интеграция для фреймворка Astro, заточенная под один сценарий: создание сайтов с документацией. Устанавливается одной командой, контент пишется в Markdown, MDX или Markdoc, а на выходе — статический сайт с профессиональным дизайном, встроенным полнотекстовым поиском (Pagefind), боковой навигацией и переключателем тем.

Starlight наследует всю архитектуру Astro: островная модель (Astro Islands), статическая генерация по умолчанию, нулевой JavaScript на клиенте, поддержка React/Vue/Svelte/Solid-компонентов при необходимости. По сути, это «Astro, заточенный под документацию» — со всеми преимуществами фреймворка и минимумом конфигурации.

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

Быстрый старт

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

npm create astro@latest -- --template starlight

Команда создаёт готовую структуру с конфигом, примерами страниц и dev-сервером.

Запуск dev-сервера

cd my-docs
npm run dev

Сайт доступен на http://localhost:4321. Все изменения в файлах применяются мгновенно через HMR.

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

Новые страницы — это файлы .md или .mdx в каталоге src/content/docs/. Структура каталогов определяет URL и автоматическую навигацию:

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

Каждый файл начинается с фронтматтера:

---
title: Быстрый старт
description: Как начать работу с проектом
---

Конфигурация

Вся конфигурация Starlight живёт в astro.config.mjs внутри вызова starlight():

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

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

Ключевые параметры

Навигация по боковой панели

Starlight поддерживает три подхода к навигации — их можно комбинировать:

Автогенерация из каталога — Starlight сканирует папку и создаёт группу:

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

Ручные ссылки — полный контроль над порядком и названиями:

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

Управление через фронтматтер — порядок, значки, скрытие:

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

Группы можно сворачивать по умолчанию через collapsed: true.

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

Starlight из коробки поддерживает многоязычные сайты. Контент разложен по каталогам — одна папка на язык:

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

Механизм резервного контента: если перевод страницы отсутствует, Starlight покажет версию на языке по умолчанию с предупреждением.

UI-строки (поиск, оглавление, навигация) уже переведены на 30+ языков, включая русский. Для кастомных строк — файлы JSON в src/content/i18n/.

Компоненты и расширение

Starlight предоставляет набор готовых компонентов для MDX-файлов:

• Card / CardGrid — карточки для навигации и обзора разделов
• Tabs / TabItem — вкладки для альтернативных инструкций (npm / pnpm / Yarn)
• Icon — встроенный набор иконок
• Aside — блоки-врезки (note, tip, caution, danger)
• Badge — значки для статусов и меток
• FileTree — визуализация файловой структуры

Кроме встроенных, можно использовать любые Astro-компоненты и компоненты на React, Vue, Svelte, Solid — Astro Islands подгрузят их только при необходимости.

Для глубокой кастомизации Starlight позволяет переопределять внутренние компоненты (Header, Sidebar, Footer и другие) через параметр components в конфиге.

Кастомизация внешнего вида

Логотип — через параметр logo в конфиге, с поддержкой раздельных версий для светлой и тёмной темы.

CSS-переменные — Starlight использует CSS Custom Properties для цветов и шрифтов. Пример замены шрифта:

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

Файл подключается через customCss: ['./src/styles/custom.css'] в конфиге.

Макеты страниц:

• doc (по умолчанию) — боковая панель + оглавление
• splash — широкий макет без боковых панелей, подходит для лендингов

Макет задаётся в фронтматтере: template: splash.

Тарифы и лимиты

Starlight — полностью бесплатный open-source проект под лицензией MIT. Ограничений на количество страниц, языков или развёртываний нет. Pagefind (встроенный поиск) тоже бесплатный и работает на клиенте без серверной инфраструктуры.

Практические сценарии

Документация open-source проекта — самый типичный кейс. Markdown в Git-репозитории, билд через CI, деплой на Netlify/Vercel/Cloudflare Pages. Ссылки «Редактировать страницу» ведут прямо в GitHub.

Внутренняя база знаний компании — закрытый сайт документации с навигацией, поиском и контролем версий через Git. При необходимости подключается SSR-адаптер для авторизации.

Многоязычная документация продукта — каталоги по языкам, резервный контент для непереведённых страниц, автоматический переключатель языков в хедере.

Технический блог с документацией — основной контент в Starlight + кастомные .astro-страницы для блога или лендинга внутри того же проекта.

Обновление

Starlight обновляется через стандартный механизм Astro:

npx @astrojs/upgrade

Команда проверит совместимость версий и предложит обновить Starlight вместе с Astro.

Ссылки

• Официальный сайт и документация
• Документация на русском
• GitHub-репозиторий
• Каталог плагинов
• Каталог тем
• Discord-сообщество Astro (канал #starlight)
• Документация Astro

По теме

• Статья: Сайт как рабочий контур: почему pimenov.ai уже не просто портфолио
• Блог: Один промпт, который заставляет Codex перепроверять себя — и реально улучшает результат
• База знаний: HTML вместо Markdown: почему ИИ-агенты генерируют в HTML и как это использовать

Если вы собираете документацию для продукта или внутренней базы знаний и хотите разобраться, как встроить Starlight в свой стек, — пишите в Telegram @pimenov.

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