Англійська для розробників VitePress

VitePress — це генератор статичних сайтів на основі Vue, зосереджений на документації, побудований на Vite для швидкого локального сервера розробки і конвеєра збирання. Цей мова став популярним вибором для документації проектів з відкритим кодом (включаючи власний сайт Vite і сайт Vue), а його словник поєднує терміни Vite/ Vue з поняттями сайтів документації, такими як « типова тема » і « налаштування за допомогою передньої частини ». Цей посібник містить всі необхідні вам терміни.

---

Основна архітектура

** Сервер розробників на базі Vite ** — VitePress успадковує швидку компіляцію на запит Vite, отже локальний перегляд оновлюється майже миттєво під час редагування файла markdown. “Ми звикли чекати кілька секунд, поки перегляд документів буде перебудований в іншому місці — з сервером розробників VitePress, що працює на Vite, зміни з’являються майже миттєво.”

** Типова тема ** — VitePress надає вам вишукану, готову до використання тему документації, яку можна налаштувати за допомогою простих параметрів налаштування, замість того, щоб створювати макет з нуля.

“Ми взагалі не створювали нетипову тему — типова тема охоплювала все, що нам було потрібно, просто налаштовувалася за допомогою config.mts.”

** Нетипова тема ** — для команд, яким потрібен повністю нетиповий дизайн, VitePress підтримує повне замінення типової теми вашими власними компонентами Vue.

• “Якщо наші вимоги до бренду вимагали дуже специфічного розкладу, ми перейшли від типової теми до нетипової теми, створеної з наших власних компонентів Vue.” *

---

Configuration

« config. mts »

Файл ** config.mts ** (або .js ) є центральним файлом налаштувань для сайту — тут зберігаються параметри заголовка, навігації, структури бічної панелі і теми.

“Додання нового елемента навігації верхнього рівня займає один рядок у config.mts — немає необхідності торкатися окремого файла маршрутизації.”

Налаштування бічної панелі

** Налаштування бічної панелі ** визначає дерево навігації, яке буде показано поряд з вмістом, або як одну загальну бічну панель, або як діапазон для кожного розділу верхнього рівня.

• “Ми розділили бічну панель на розділи, отже, у розділах « Довідка » і « Довідка щодо API » буде показано відповідні розділи навігації замість одного довгого об’ єднаного списку.” *

Конфігурація Frontmatter Driven

Багато параметрів рівня сторінки — наприклад, вимкнення бічної панелі для певної сторінки або встановлення нетипового розкладу — керується за допомогою ** frontmatter **, а не окремого налаштування маршрутизації.

“Ми вимикаємо бічну панель на сторінці призначення, просто вставляючи layout: home в її передній частині — зміна коду не потрібна.”

---

Розширення Markdown

** Нетипові контейнери ** — специфічний для VitePress синтаксис markdown (наприклад, ::: tip або ::: warning ) для відтворення стилізованих блоків підписів без написання сирого HTML.

“Ми загорнули попередження про міграцію в контейнер ::: warning, щоб воно виділяється з навколишньої прози.”

** Code group ** — розширення markdown, яке надає вам змогу показувати один і той же приклад у декількох мовах або менеджерах пакунків у вигляді табів (наприклад, npm, yarn, pnpm ) у межах одного блоку коду.

“Замість трьох окремих блоків коду для npm, yarn і pnpm, ми використовуємо групу коду — читачі просто натискають вкладку для свого менеджера пакунків.”

** Підсвічування рядків ** — синтаксис підсвічування для підсвічування певних рядків у блоку коду, який буде корисним для привернення уваги до конкретного рядка, який обговорюється у навколишньому тексті.

• “Ми підсвічили рядок 4 у фрагменті, оскільки це рядок, який буде детально пояснено у наступному абзаці.” *

---

Інтеграція

** Компоненти Vue у markdown ** — оскільки VitePress працює на Vue, ви можете імпортувати і використовувати компоненти Vue безпосередньо у файлах markdown, подібно до MDX у екосистемі React.

• “Ми вбудували живий, інтерактивний компонент Vue безпосередньо на сторінку документації, щоб читачі могли спробувати API, не залишаючи документацію.” *

** Composable ** — частина логіки стану, яка може використовуватися повторно (концепція API Vue Composition), яку може використовувати нетипова тема або вбудований компонент, спільно використовувати її на декількох сторінках.

“Ми написали невеликий компонент, який відстежує вибір користувачем менеджера пакунків, щоб вкладки груп коду залишалися синхронними на всьому сайті.”

---

Розробка і впровадження

** Статичний вивід збирання ** — VitePress виробляє повністю статичний HTML / JS / CSS набір у час збирання, розгорнутий на будь-який статичний вузол без сервера Node.js під час виконання.

“Немає сервера для запуску у виробничому режимі — вивід збирання — це статичні файли, які ми можемо розгорнути прямо в будь-який CDN.”

** Перевірка мертвих посилань ** — VitePress можна налаштувати так, щоб збірка зазнавала невдачі, якщо внутрішні посилання з позначень вказують на сторінки, яких не існує, перехоплюючи пошкоджені посилання перед розгортанням.

“Ми ввімкнули перевірку мертвих посилань у CI, тому внутрішнє посилання з помилкою тепер не буде збудовано замість того, щоб тихо відправляти помилку 404.”

---

Використовується для передачі команди

Situation	Phrase
Justifying the choice for a Vue-ecosystem project	”Since our team already writes Vue daily, extending the theme with our own components felt natural — there’s no separate templating language to learn.”
Explaining a config change	”Adding the new section to the sidebar is a config change, not a code change — anyone comfortable editing JSON-like config can do it.”
Describing dead link checking	”The build now fails on broken internal links deliberately — it’s meant to catch stale references before they reach production, not to block you unnecessarily.”
Discussing deployment	”There’s no runtime server involved — we’re deploying the static build output straight to a CDN, same as any other static site.”

Поширені помилки

• Використання VitePress « просто markdown » — підтримка вбудовування справжніх компонентів Vue у вміст, що є значно відмінною можливістю від простого markdown.
• Використання фрази « бічну панель пошкоджено », коли насправді ** текст на сторінці ** навмисно перезаписує загальні параметри бічної панелі — перевірте текст на сторінці, перш ніж вважати, що це помилка.
• Плутанина ** нетипового контейнера ** (синтаксис підказок у стилі документації) з ** нетиповою темою ** (повна заміна компонентів Vue сайту) — вони вирішують дуже різні проблеми.

Практичні вправи

1. Поясніть у двох реченнях різницю між типовою темою і нетиповою темою у VitePress.
2. Написати короткий опис PR для додавання групи коду до сторінки документації, яка раніше мала окремі блоки коду для кожного менеджера пакунків.
3. Написати коротке пояснення для співробітника команди, чому у CI увімкнено перевірку непрацездатних посилань і що робити, якщо збірка завершиться невдало.

Зв’язані ресурси

• Англійська для розробників Docusaurus
• Англійська для розробників Vue
• Англійська для розробки додатків Vite

Навигація документаційної екосистеми — це початкова стадія для команд

VitePress пропонує гнучкий і ефективний спосіб створення сайтів документації, використовуючи переваги Vue.js і робочий процес розробки Vite. Ефективне спілкування в рамках міжнародних команд, що будують ці сайти, має вирішальне значення, особливо щодо технічних специфікацій і спільних робочих потоків. Цей розділ присвячено ключовим словам, які використовуються у дискусіях щодо налаштування VitePress, вибору тем і загальної архітектури сайту — це розділ призначено для розробників, які можуть вивчати професійні англійські фрази і термінологію.

Одним з перших викликів для команд, які приймають VitePress, є розуміння * конфігурації, що керується * природою навігації. Ми часто обговорюємо такі поняття, як « маршрутизація », « схема » і « метадані » у зв’язку з тим, як вміст структурується і доступний на сайті документації. Це не просто про додавання сторінок; це про визначення чіткої, машинно-читабельної структури, яку VitePress може інтерпретувати, щоб генерувати посилання, які можна переглядати. Наприклад, замість того, щоб сказати «додати сторінку для «Початок роботи»,» ми б обговорили «визначення схеми для розділу «Початок роботи», включаючи метадані для назви, опису і пов’язаного вмісту»

Іншою областю, де точна мова є важливою, є обговорення налаштування тем - особливо з покладанням VitePress на компоненти Vue. Часто використовуються такі терміни, як «компонентний стиль», «CSS-модулі» і «відтворення шаблонів». Зазвичай, під час перегляду коду ви можете почути такий коментар: « Чи могли б ви переробити стиль цього компонента, щоб використовувати модулі CSS для кращого підтримування і розширення обсягу? » Це не просто пропозиція; це інструкція, заснована на встановлених найкращих практиках і спільному розумінні того, як зазвичай працюють теми VitePress.

Нарешті, комунікація навколо сервера розробки - *Vite-based dev server * - є критичним під час процесу збирання. Про проблеми можуть повідомляти як «сервер Vite не з’єднується правильно», або розробники запросять «перебудувати з Vite», щоб переконатися, що вони використовують найновіші оптимізації і стратегії кешування. Зрозуміти ці нюанси є життєво важливим для ефективного співробітництва.

// Example: VitePress configuration using TypeScript (simplified)
const vitepressConfig = {
  title: 'My Awesome Documentation Site',
  description: 'A beautiful documentation site built with VitePress.',
  plugins: [
    {
      name: 'my-plugin',
      async beforeAllPagesResolve(page, id) {
        // Example: Modify page metadata (not common, but illustrates the concept)
        if (id === '/getting-started') {
          this.page.metadata = {
            title: 'Getting Started with VitePress',
            description: 'A quick introduction to using VitePress.'
          };
        }
      },
    },
  ],
};

console.log(vitepressConfig);

У цьому прикладі показано спрощений об’ єкт налаштування. Зауважте використання описових ключів, таких як title, description, і plugins. Функція beforeAllPagesResolve підкреслює, як метадані - ключові для навігації і відображення контенту - управляються, вирівнюючи з попередньою дискусією про схему і маршрутизацію. Сам код не є просто фрагментом; це ілюстрація типу конфігурації, яка буде обговорюватися в команді, з акцентом на чітку документацію і структурований обмін даними.