Astro vs VitePress: Что выбрать для документации

VitePress и Astro Starlight — два лидера в нише генераторов документации в 2026 году. VitePress создан командой Vue.js и используется для документации Vue, Vite, Vitest. Astro Starlight — официальное решение от команды Astro. Разбираем, что выбрать.

Что такое VitePress?

VitePress — это SSG, специально созданный для технической документации. Написан на Vue 3, работает поверх Vite. Используется для:

• Официальная документация Vue
• Документация Vite
• Документация Vitest
• Rollup

VitePress идеален, если ваш проект в экосистеме Vue.

Что такое Astro Starlight?

Starlight — официальный шаблон Astro для документации. Подробнее в статье Документация на Astro Starlight. Используется для:

• Документация Astro
• Документация Biome
• Многочисленных open-source проектов

Сравнение

Синтаксис: небольшие различия в Markdown

VitePress — специальные «контейнеры»:

::: tip Совет
Используйте это для подсказок.
:::

::: warning Предупреждение
Будьте осторожны!
:::

::: code-group

```js [config.js]
const config = { ... }
```

const config: Config = { ... }

:::

**Astro Starlight** — через MDX и специальные компоненты:

```mdx
import { Tabs, TabItem } from '@astrojs/starlight/components';

:::tip[Совет]
Используйте это для подсказок.
:::

:::caution
Будьте осторожны!
:::

<Tabs>
  <TabItem label="config.js">```js
  const config = { ... }
  ```</TabItem>
  <TabItem label="config.ts">```ts
  const config: Config = { ... }
  ```</TabItem>
</Tabs>

Поиск: принципиальное отличие

VitePress использует minisearch по умолчанию (встроен, без API). Для крупных проектов — Algolia DocSearch (требует аккаунт и синхронизацию индекса).

Astro Starlight использует Pagefind — статический поисковый движок:

• ✅ Работает офлайн
• ✅ Бесплатно, без аккаунтов
• ✅ Автоматически обновляется при каждой сборке
• ✅ Поддерживает поиск по нескольким языкам
• ⚠️ Чуть медленнее на очень больших сайтах (> 10 000 страниц)

Кастомизация интерфейса

VitePress — через Vue-компоненты и CSS-переменные:

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme';
import MyComponent from './MyComponent.vue';

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('MyComponent', MyComponent);
  },
};

Starlight — через Astro-компоненты-слоты и CSS:

// astro.config.mjs
starlight({
  components: {
    // Переопределить встроенные компоненты
    Header: './src/overrides/Header.astro',
    Footer: './src/overrides/Footer.astro',
  },
});

Vue-компоненты в документации

В VitePress Vue-компоненты работают нативно в Markdown — просто пишите <MyComponent />:

## Пример использования

<InteractiveDemo />

Выше — интерактивная демонстрация.

В Astro Starlight Vue-компоненты работают как острова через @astrojs/vue:

import { VueComponent } from '../components/VueComponent.vue';

<VueComponent client:visible />

Для каких проектов что подходит

Выбирайте VitePress если:

• Проект в экосистеме Vue (Vue 3, Vite, Nuxt, Pinia)
• Нужны нативные Vue-компоненты в документации
• Важна максимальная скорость сборки
• Нужно полноценное версионирование через плагин

Выбирайте Astro Starlight если:

• Проект независим от Vue-экосистемы
• Нужен автономный поиск (Pagefind, без Algolia)
• Хотите использовать React/Svelte-компоненты в документации
• Важен максимальный PageSpeed
• Нужна мульти-фреймворк совместимость

Конфигурация: сравнение

VitePress (docs/.vitepress/config.ts):

import { defineConfig } from 'vitepress';

export default defineConfig({
  title: 'My Project',
  description: 'Documentation',
  themeConfig: {
    nav: [{ text: 'Guide', link: '/guide/' }],
    sidebar: {
      '/guide/': [{ text: 'Introduction', link: '/guide/' }],
    },
    socialLinks: [{ icon: 'github', link: '...' }],
  },
});

Starlight (astro.config.mjs):

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Project',
      description: 'Documentation',
      sidebar: [{ label: 'Guide', autogenerate: { directory: 'guide' } }],
      social: { github: '...' },
    }),
  ],
});

Итог

Оба инструмента превосходны для технической документации. VitePress — естественный выбор для Vue-проектов с отличным DX и нативными Vue-компонентами в Markdown. Astro Starlight — лучший выбор для независимых проектов, где важны PageSpeed 100, автономный поиск Pagefind и мульти-фреймворк гибкость. В 2026 году оба инструмента активно развиваются — вы не ошибётесь ни с одним.