התאמת ערכת נושא של VitePress: CSS, Layout Slots ורכיבים

/* .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 הם נקודות הזרקה ברכיב nav-bar-content-before. השתמש בהם כדי להכניס את רכיבי ה-Vue שלך לניווט, פוטר, סרגל צד וכו'. הרשימה המלאה של ה-slots מתוארת בתיעוד הרשמי של VitePress. העיקריים: 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; .

דוגמת רישום:

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

כיצד לדרוס רכיבי ערכת נושא ברירת מחדל?

אם ה-slots אינם מספיקים, דרוס כל רכיב ערכת נושא דרך 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. במקום עיצוב ידני, יצרנו רכיב <!-- .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> אוניברסלי המציג method, path, תיאור ו-slot לגוף הבקשה. בעבר, עיצוב ידני של תיעוד צרך 20 שעות בחודש, וגרם לעלויות משמעותיות. לאחר יישום הרכיב, הזמן ירד ל-5 שעות בחודש, וחסך 15 שעות חודשיות (כ-$2,000 בחודש). מספר השגיאות בתיאורים ירד ב-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

VitePress מול מחוללי תיעוד סטטי אחרים

VitePress מאפשר להתאים ערכת נושא פי 2–3 מהר יותר מ-Docusaurus: זמן התקנה ממוצע לסגנון ארגוני הוא יומיים לעומת 5–7 ימים עבור Docusaurus. Vue.js הוא הבסיס של VitePress.

תהליך ההתאמה שלנו

1. ניתוח — לימוד ה-mockup של המעצב וערכת הנושא הקיימת, זיהוי נקודות התאמה.
2. עיצוב — קביעה אילו משתני CSS ו-slots נדרשים, עיצוב רכיבים.
3. יישום — כתיבת CSS, יצירת רכיבים, הגדרת Layout.
4. בדיקות — אימות בערכות נושא בהירות וכהות, מכשירים ניידים, דפדפנים שונים.
5. פריסה — פרסום התיעוד, הבטחת תקינות מלאה.

מה כלול

יש לנו ניסיון של 7+ שנים בפתרונות תיעוד והשלמנו מעל 50 פרויקטים של התאמת VitePress. השירות שלנו כולל:

• ערכת נושא מותאמת עם משתני CSS לסגנון ארגוני;
• רכיבים מותאמים אישית (עד 5);
• תיעוד לתחזוקה עתידית;
• גישה למאגר הקוד;
• אחריות תאימות עם VitePress 1.x.

לוח זמנים: מ-3 עד 7 ימים בהתאם להיקף. התמחור נקבע לאחר ניתוח.

מוכנים להתחיל? צרו קשר לייעוץ—נדון בפרטי הפרויקט שלכם. קבלו הערכת עלות אישית ופתרון אופטימלי לתיעוד שלכם.