Стандартная тема 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 дней в зависимости от объёма. Стоимость рассчитывается индивидуально.
Готовы приступить? Свяжитесь с нами для консультации — обсудим детали вашего проекта. Получите индивидуальный расчёт стоимости и оптимальное решение для вашей документации.