Збірка документації — рутина, яку багато хто відкладає. 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.
Зв'яжіться з нами, щоб обговорити ваш проект. Ми оцінимо обсяг роботи та запропонуємо оптимальне рішення. Або просто замовте розробку — і отримайте готовий сайт документації в стислі строки.