Настройка и кастомизация темы VitePress

Настройка и кастомизация темы VitePress

VitePress предоставляет Default Theme с широкими возможностями кастомизации через CSS-переменные и Layout slots, либо полное переопределение через Custom Theme.

CSS-переменные

/* .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;
}

Расширение Default Theme (Layout slots)

// .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;

Кастомный Home Layout

<!-- .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="frontmatter.hero.image?.alt">
    </div>
  </section>
</template>

Компонент для API-документации

<!-- .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="Creates a new user">

**Request body**

| Field | Type | Required |
|---|---|---|
| name | string | Yes |
| email | string | Yes |

</ApiEndpoint>

Кастомизация темы VitePress с 3–5 компонентами — 1–3 дня.