Стандартная тема VitePress часто не соответствует корпоративному стилю. Разработчики тратят от 3 до 10 дней на базовую кастомизацию, не зная архитектуры — по опросу, 70% сталкиваются с этой проблемой. Наши инженеры разработали системный подход: CSS-переменные, Layout slots и переопределение компонентов. Такой метод сокращает время настройки до 1-2 дней для типовых изменений и до 7 дней для полной кастомизации с кастомными компонентами. Рассмотрим каждый механизм на примере финтех-проекта с 30+ REST-эндпоинтами: ручное форматирование документации отнимало 20 часов в месяц, после внедрения компонента время сократилось до 5 часов, а количество ошибок в описаниях снизилось на 40%.
Как кастомизировать VitePress через CSS-переменные?
Default Theme предоставляет десятки CSS-переменных, управляющих цветами, шрифтами, отступами. Достаточно переопределить их в custom.css, чтобы привести тему к корпоративному стилю. Основные группы переменных:
- Цвета:
--vp-c-brand-1,--vp-c-brand-2,--vp-c-brand-3,--vp-c-text-1,--vp-c-bgи т.д. - Типографика:
--vp-font-family-base,--vp-font-family-mono,--vp-font-size-base. - Отступы и размеры:
--vp-nav-height,--vp-sidebar-width,--vp-content-max-width.
/* .vitepress/theme/custom.css */ :root { --vp-c-brand-1: #2563eb; --vp-c-brand-2: #1d4ed8; --vp-c-brand-3: #1e40af; --vp-font-family-base: 'Inter', system-ui, sans-serif; --vp-code-font-family: 'JetBrains Mono', monospace; --vp-nav-height: 64px; --vp-sidebar-width: 272px; } .dark { --vp-c-bg: #0f172a; --vp-c-bg-soft: #1e293b; --vp-c-divider: #334155; } Эти изменения сразу применяются ко всем страницам. Время настройки — около часа.
Что такое Layout slots и как их использовать?
Layout slots — точки инъекции в компоненте DefaultTheme.Layout. С их помощью вставляют свои Vue-компоненты в навигацию, подвал, сайдбар. Полный список слотов описан в официальной документации VitePress. Основные из них: nav-bar-content-before, nav-bar-content-after, sidebar-top, sidebar-bottom, content-top, content-bottom, doc-before, doc-after, doc-footer-before, doc-footer-after, aside-top, aside-bottom, aside-outline-before, aside-outline-after, home-hero-before, home-hero-info, home-hero-info-after, home-features-before, home-features-after, layout-top, layout-bottom.
Пример регистрации:
// .vitepress/theme/index.ts import { h } from 'vue'; import type { Theme } from 'vitepress'; import DefaultTheme from 'vitepress/theme'; import './custom.css'; import MyBanner from './components/MyBanner.vue'; import ApiEndpoint from './components/ApiEndpoint.vue'; export default { extends: DefaultTheme, Layout: () => { return h(DefaultTheme.Layout, null, { 'nav-bar-content-after': () => h(SearchButton), 'home-hero-info-after': () => h(MyBanner), 'doc-before': () => h(BreadcrumbNav), 'doc-footer-before': () => h(FeedbackWidget), 'aside-bottom': () => h(TableOfContentsEnhanced), }); }, enhanceApp({ app, router, siteData }) { app.component('ApiEndpoint', ApiEndpoint); app.component('Badge', Badge); }, } satisfies Theme; Как переопределить компоненты Default Theme?
Если слотов недостаточно, переопределите любой компонент темы через extends. Например, кастомный Home Layout даёт полный контроль над секцией hero, колонками фич и призывами к действию.
<!-- .vitepress/theme/components/HomeHero.vue --> <script setup lang="ts"> import { useData } from 'vitepress'; const { frontmatter } = useData(); </script> <template> <section class="hero"> <div class="hero-content"> <h1>{{ frontmatter.hero.name }}</h1> <p>{{ frontmatter.hero.tagline }}</p> <div class="hero-actions"> <a v-for="action in frontmatter.hero.actions" :key="action.text" :href="action.link" :class="['btn', `btn--${action.theme}`]" > {{ action.text }} </a> </div> </div> <div class="hero-image"> <img :src="frontmatter.hero.image?.src" alt="Кастомный Hero-компонент VitePress"> </div> </section> </template> Как разработать компонент для API-документации?
Из практики: клиент — финтех-стартап с 30+ REST-эндпоинтами. Вместо ручного форматирования создали универсальный компонент ApiEndpoint, который отображает метод, путь, описание и слот для тела запроса. Раньше ручное форматирование документации отнимало 20 часов в месяц, что обходилось существенными затратами. После внедрения компонента время сократилось до 5 часов в месяц, экономия составила 15 часов ежемесячно. Количество ошибок в описаниях снизилось на 40%, а сайт с документацией посещает 5k+ разработчиков.
<!-- .vitepress/theme/components/ApiEndpoint.vue --> <script setup lang="ts"> defineProps<{ method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; path: string; description?: string; }>(); </script> <template> <div class="api-endpoint"> <div class="api-endpoint__header"> <span :class="`method method--${method.toLowerCase()}`">{{ method }}</span> <code class="api-endpoint__path">{{ path }}</code> </div> <p v-if="description" class="api-endpoint__desc">{{ description }}</p> <slot /> </div> </template> <style scoped> .method { padding: 2px 8px; border-radius: 4px; font-weight: 600; font-size: 12px; } .method--get { background: #d1fae5; color: #065f46; } .method--post { background: #dbeafe; color: #1e40af; } .method--delete { background: #fee2e2; color: #991b1b; } </style> Использование в Markdown:
<ApiEndpoint method="POST" path="/api/v1/users" description="Создаёт нового пользователя"> **Request body** | Field | Type | Required | |---|---|---| | name | string | Yes | | email | string | Yes | </ApiEndpoint> Типичные ошибки при кастомизации VitePress
| Ошибка | Последствие | Решение |
|---|---|---|
| Переопределение CSS-переменных без учёта тёмной темы | Конфликт цветов в dark mode | Добавлять .dark селектор |
| Использование слотов не по назначению | Нарушение семантики и доступности | Изучить официальную документацию |
| Попытка переопределить компонент без extends | Потеря функциональности Default Theme | Всегда использовать extends: DefaultTheme |
Забыть зарегистрировать компонент в enhanceApp | Ошибка при рендеринге шаблона | Регистрировать глобальные компоненты в enhanceApp |
Сравнение VitePress с другими генераторами статической документации
| Инструмент | Язык шаблонов | Кастомизация | Скорость сборки | Подходит для |
|---|---|---|---|---|
| VitePress | Vue 3 | CSS-переменные, слоты, extends | <2 с (1000 файлов) | Проекты на Vue/React с быстрой документацией |
| Docusaurus | React | Swizzling, CSS | <5 с | Документация больших open-source проектов |
| GitBook | Markdown | Тема с ограниченными настройками | <1 с | Простая документация без сложной кастомизации |
| MkDocs | Python/Markdown | Плагины, темы | <3 с | Техническая документация на Python |
VitePress позволяет настроить тему в 2-3 раза быстрее, чем Docusaurus: среднее время настройки под корпоративный стиль — 2 дня против 5–7 у Docusaurus. Vue.js — основа VitePress.
Процесс работы над кастомизацией
- Анализ — изучаем макет дизайнера и существующую тему, выявляем точки кастомизации.
- Проектирование — определяем, какие CSS-переменные и слоты потребуются, проектируем компоненты.
- Реализация — пишем CSS, создаём компоненты, настраиваем Layout.
- Тестирование — проверяем на светлой и тёмной теме, на мобильных устройствах, в разных браузерах.
- Деплой — публикуем документацию, убеждаемся, что всё работает.
Что входит в работу
Мы имеем 7+ лет опыта в разработке документационных решений и выполнили более 50 проектов по кастомизации VitePress. В рамках услуги предоставляем:
- настроенную тему с CSS-переменными под корпоративный стиль;
- кастомные компоненты (до 5 штук);
- документацию по дальнейшей поддержке;
- доступ к репозиторию;
- гарантию совместимости с VitePress 1.x.
Сроки: от 3 до 7 дней в зависимости от объёма. Стоимость рассчитывается индивидуально.
Готовы приступить? Свяжитесь с нами для консультации — обсудим детали вашего проекта. Получите индивидуальный расчёт стоимости и оптимальное решение для вашей документации.