Сборка документации — рутина, которую многие откладывают. Docusaurus тормозит на больших проектах (500 страниц собираются 5 минут), GitBook стоит денег, а самописное решение отнимает дни. VitePress решает эти проблемы: статика на Vite и Vue 3, время сборки — секунды, а не минуты. Мы настроим такой сайт под ключ: от структуры до деплоя. Получите консультацию, чтобы обсудить ваш проект.
Почему VitePress подходит для документации?
VitePress — не просто генератор, а экосистема для технической документации. Он быстрее аналогов при сборке (3 секунды на 200 страниц), нативно поддерживает Vue-компоненты в Markdown и легко настраивается. Например, согласно документации VitePress, hydration mismatch не возникает, так как это статика — нет SSR. LCP и FCP минимальны за счёт предзагрузки, что обеспечивает идеальные Core Web Vitals. Статические файлы требуют дешёвого хостинга — экономия до 70% по сравнению с динамическими CMS.
Сравнение VitePress с другими генераторами
| Генератор | Скорость сборки | Кастомизация | Поиск | Стоимость |
|---|---|---|---|---|
| VitePress | Мгновенная | Vue-компоненты + CSS | Algolia / локальный | Бесплатно |
| Docusaurus | Средняя | React-компоненты | Algolia | Бесплатно |
| GitBook | Медленная | Ограниченная | Встроенный | От $6.75/мес |
VitePress выигрывает по скорости и гибкости кастомизации, особенно если вы используете Vue-стек.
Основные проблемы и их решения
1. Генерация сайдбара из файловой структуры. Ручное описание сайдбара для большого проекта — ад. Мы автоматизируем этот процесс: пишем скрипт, который сканирует папки и строит меню. Код ниже читает все .md файлы, исключая index.md, и создаёт массив ссылок.
// .vitepress/utils/generateSidebar.ts
import fs from 'fs';
import path from 'path';
export function generateSidebar(dir: string) {
const files = fs.readdirSync(dir);
return files
.filter(f => f.endsWith('.md') && f !== 'index.md')
.map(f => ({
text: f.replace('.md', '').replace(/-/g, ' '),
link: `/${path.relative('docs', path.join(dir, f)).replace('.md', '')}`,
}));
}
2. Настройка полнотекстового поиска. Встроенный поиск ограничен. Мы подключаем Algolia: настраиваем краулер, конфигурируем индексы (до 10 000 записей) и добавляем виджет. Это даёт быстрый и точный поиск по всем страницам.
3. Кастомные Vue-компоненты в Markdown. Хотите интерактивный пример кода или калькулятор? Добавляем любой Vue-компонент в разметку. VitePress поддерживает SFC прямо в документации.
# Component Demo
<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>
<button @click="count++">Count: {{ count }}</button>
::: tip
This is a tip container.
:::
::: warning
This is a warning.
:::
::: code-group
```sh [npm]
npm install my-package
pnpm add my-package
:::
### Как мы это делаем?
Используем стек: VitePress latest, Vue 3 Composition API, TypeScript, Tailwind для стилизации. Настраиваем конфиг под ваш бренд: логотип, фавикон, мета-теги. Подключаем аналитику, карту сайта, RSS-ленту, настраиваем CI/CD через GitHub Actions с кэшированием node_modules. Пример полного конфига:
```typescript
// .vitepress/config.ts
import { defineConfig } from 'vitepress';
export default defineConfig({
title: 'My Project',
description: 'Documentation for My Project',
lang: 'ru-RU',
themeConfig: {
nav: [
{ text: 'Guide', link: '/guide/introduction' },
{ text: 'API', link: '/api/overview' },
{ text: 'Changelog', link: '/changelog' },
],
sidebar: {
'/guide/': [
{ text: 'Introduction', items: [
{ text: 'What is My Project?', link: '/guide/introduction' },
{ text: 'Getting Started', link: '/guide/getting-started' },
{ text: 'Configuration', link: '/guide/configuration' },
]},
{ text: 'Advanced', items: [
{ text: 'Plugins', link: '/guide/plugins' },
{ text: 'API', link: '/guide/api' },
]},
],
},
search: {
provider: 'algolia',
options: {
appId: 'APP_ID',
apiKey: 'API_KEY',
indexName: 'my-project',
},
},
editLink: {
pattern: 'https://github.com/my-org/my-project/edit/main/docs/:path',
text: 'Edit this page',
},
socialLinks: [
{ icon: 'github', link: 'https://github.com/my-org/my-project' },
],
},
markdown: {
theme: { light: 'github-light', dark: 'github-dark' },
config(md) {
md.use(require('markdown-it-container'), 'tip');
},
},
});
Как настроить поиск на сайте VitePress?
Поиск — критичный элемент документации. Мы настраиваем Algolia: создаём приложение, загружаем краулер, конфигурируем индексацию по селекторам. Затем интегрируем виджет в тему. Альтернатива — локальный поиск через @algolia/autocomplete-js, но он требует бэкенда. Для статики Algolia оптимален.
Процесс работы
- Аналитика — разбираем структуру вашей документации, решаем, что оставить, что переписать.
- Проектирование — разрабатываем схему сайдбара, навигацию, SEO-структуру URL.
- Реализация — настраиваем VitePress, пишем кастомные компоненты, подключаем поиск.
- Тестирование — проверяем все ссылки, адаптивность, производительность через Lighthouse.
- Деплой — выгружаем статику на ваш хостинг, настраиваем CI/CD (например, через GitHub Actions).
Ориентировочные сроки
| Этап | Срок |
|---|---|
| Базовая настройка + 1 раздел | 2 дня |
| Кастомная тема + поиск | 3 дня |
| Полный проект (5+ разделов) | 5 дней |
Стоимость рассчитывается индивидуально, зависит от объёма документации и сложности кастомизации.
Что входит в работу
- Готовый репозиторий с конфигурацией VitePress
- Кастомная тема (стили, логотип, favicon)
- Автоматическая генерация сайдбара
- Интеграция поиска (Algolia или локальный)
- Настройка деплоя на Vercel/Cloudflare Pages
- Документация по редактированию контента
- 1 час поддержки после запуска
Типичные ошибки при самостоятельной настройке
- Неправильный
basepath — если сайт не в корне домена, нужно указатьbaseв конфиге, иначе ресурсы не загрузятся. - Отсутствие
editLink— пользователи не могут предложить правки, что снижает доверие. - Игнорирование SEO — не прописаны мета-теги, Open Graph, карта сайта, из-за чего сайт плохо индексируется.
- Сборка сайдбара вручную — при добавлении новых страниц забывают обновить конфиг. Автоматизация решает эту проблему.
Наш опыт
Мы занимаемся разработкой сайтов документации более 5 лет. Реализовали проекты для API-сервисов, библиотек, корпоративных продуктов. Гарантируем, что сайт будет соответствовать современным стандартам производительности и SEO.
Свяжитесь с нами, чтобы обсудить ваш проект. Мы оценим объём работы и предложим оптимальное решение. Или просто закажите разработку — и получите готовый сайт документации в сжатые сроки.