Astro Starlight — официальный шаблон для создания технической документации. В 2026 году это один из лучших инструментов в своём классе, наравне с Docusaurus и VitePress. Встроенный поиск, i18n, версионирование, тёмная тема — всё из коробки.

Почему Starlight?

Starlight создан командой Astro и является showcase-проектом фреймворка. Он демонстрирует все возможности Astro для контентных сайтов:

Встроенный поиск через Pagefind (работает офлайн, без внешних API)
i18n — документация на нескольких языках
Версионирование — docs v1, v2, v3 параллельно
Тёмная/светлая тема — автоматически
Боковое меню — автогенерация из файловой структуры
PageSpeed 95-100 — Astro-основа

Официальная документация Astro написана на Starlight. Это лучшая демонстрация его возможностей.

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

code

# Создать новый Starlight-проект
npm create astro@latest -- --template starlight

# Или добавить Starlight к существующему Astro-проекту
npx astro add starlight

Структура после установки:

code

docs/
├── src/
│   ├── assets/              # Изображения для статей
│   ├── content/
│   │   └── docs/            # Markdown/MDX файлы документации
│   │       ├── index.mdx    # Главная страница
│   │       ├── getting-started.md
│   │       └── guides/
│   │           ├── installation.md
│   │           └── configuration.md
│   └── env.d.ts
├── astro.config.mjs
└── package.json

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

code

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

export default defineConfig({
  site: 'https://docs.yourproject.ru',
  integrations: [
    starlight({
      title: 'YourProject Docs',
      description: 'Официальная документация YourProject',

      // Языки
      defaultLocale: 'ru',
      locales: {
        ru: { label: 'Русский', lang: 'ru' },
        en: { label: 'English', lang: 'en' },
      },

      // Социальные ссылки в header
      social: {
        github: 'https://github.com/yourorg/yourproject',
        telegram: 'https://t.me/yourproject',
      },

      // Боковая навигация
      sidebar: [
        {
          label: 'Начало работы',
          items: [
            { label: 'Введение', slug: 'introduction' },
            { label: 'Установка', slug: 'getting-started' },
            { label: 'Конфигурация', slug: 'configuration' },
          ],
        },
        {
          label: 'Руководства',
          autogenerate: { directory: 'guides' }, // Автогенерация из папки
        },
        {
          label: 'API Reference',
          autogenerate: { directory: 'api' },
          badge: { text: 'v2', variant: 'tip' },
        },
      ],

      // Кастомизация темы
      customCss: ['./src/styles/custom.css'],

      // Логотип
      logo: {
        light: './src/assets/logo-light.svg',
        dark: './src/assets/logo-dark.svg',
        replacesTitle: true,
      },
    }),
  ],
});

Frontmatter страниц документации

code

---
# Обязательные поля Starlight
title: Установка и первый запуск
description: Как установить YourProject за 5 минут

# Навигация
sidebar:
  order: 1 # Порядок в меню
  badge: # Бейдж рядом с названием
    text: Новое
    variant: tip

# Хлебные крошки
prev:
  link: /introduction/
  label: Введение
next:
  link: /configuration/
  label: Конфигурация

# Разное
draft: false # Черновик — не показывать
---

## Установка через npm

```bash
npm install yourproject
```

code


## Встроенный поиск Pagefind

Starlight использует **Pagefind** — статический поисковый движок, который работает без серверов и без внешних API:

```js
// Pagefind работает автоматически — ничего настраивать не нужно!
// После `astro build` поиск индексирует весь контент
// Поисковый интерфейс встроен в Starlight-тему

В отличие от Algolia (который требует аккаунт и синхронизацию), Pagefind:

Работает офлайн
Бесплатен
Автоматически обновляется при каждой сборке
Не требует API-ключей

Многоязычная документация

code

src/content/docs/
├── ru/                  # Русская версия
│   ├── getting-started.md
│   └── guides/
│       └── installation.md
└── en/                  # Английская версия
    ├── getting-started.md
    └── guides/
        └── installation.md

Starlight автоматически добавляет языковой переключатель и управляет URL-путями (/ru/, /en/).

Кастомизация дизайна

code

/* src/styles/custom.css */

/* Изменить цвета Starlight */
:root {
  --sl-color-accent: #6d28d9; /* Основной цвет */
  --sl-color-accent-high: #7c3aed;
  --sl-color-text-accent: #a78bfa;
}

[data-theme='dark'] {
  --sl-color-accent: #818cf8;
  --sl-color-accent-high: #a5b4fc;
}

/* Кастомный шрифт */
:root {
  --sl-font: 'Inter', sans-serif;
}

info

Asides (колонки)

Starlight включает специальные блоки :::note, :::tip, :::caution. Они выделяются цветом и иконкой для привлечения внимания.

tab

Вкладки

Компонент <Tabs> показывает примеры кода для разных ОС или пакетных менеджеров: npm / yarn / pnpm.

grid_view

Card Grid

<CardGrid> с <Card> — красивые карточки для навигации по разделам на главной странице документации.

Версионирование

Для нескольких версий документации — используйте разные ветки Git или подпапки:

code

src/content/docs/
├── v1/
│   └── api.md
└── v2/
    └── api.md

code

// astro.config.mjs
sidebar: [
  {
    label: 'API v2 (актуальная)',
    autogenerate: { directory: 'v2' },
    badge: { text: 'Latest', variant: 'success' },
  },
  {
    label: 'API v1 (устаревшая)',
    autogenerate: { directory: 'v1' },
    badge: { text: 'Legacy', variant: 'caution' },
  },
],

Starlight vs Docusaurus

Параметр	Starlight	Docusaurus
Основа	Astro	React
PageSpeed	98-100	75-88
Поиск	Pagefind (встроен)	Algolia DocSearch
Кастомизация	CSS-переменные	React-компоненты
JS на клиенте	~20 KB	~150 KB
i18n	✅ Встроен	✅ Встроен
Версионирование	Ручное	✅ Встроено
Экосистема	Молодая	Огромная (Meta)

Деплой

Starlight — статический сайт. Любой CDN:

code

npm run build
# dist/ → Cloudflare Pages, Vercel, Netlify, GitHub Pages

Для автодеплоя при пуше в GitHub:

code

# .github/workflows/deploy.yml
name: Deploy Docs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          projectName: my-docs
          directory: dist

Итог

Astro Starlight — лучший выбор для технической документации open-source проектов и продуктов в 2026 году. Встроенный поиск, i18n, тёмная тема, PageSpeed 100 и простота настройки через единый astro.config.mjs делают его на голову выше любых других инструментов. Если ваш проект растёт — документация на Starlight растёт вместе с ним.

Документация на Astro Starlight: Полный гайд 2026

Почему Starlight?

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

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

Frontmatter страниц документации

Многоязычная документация

Кастомизация дизайна

Asides (колонки)

Вкладки

Card Grid

Версионирование

Starlight vs Docusaurus

Деплой

Итог

Комментарии

Оставить комментарий

Рекомендуем к прочтению

Базы данных для Astro

Идеальный стек на Astro в 2026

Готовые интеграции Astro