Створення та запуск проекту VitePress із ServBay

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

Під час локальної розробки та тестування сайтів на VitePress дуже важливо мати стабільне та зручне у налаштуванні локальне веб-середовище. Саме цим і є ServBay — платформа, що об’єднує різні версії Node.js та потужні веб-сервери (наприклад Caddy чи Nginx), що дозволяють без зусиль обслуговувати ваші проекти на VitePress.

У цьому матеріалі ви дізнаєтеся, як скористатися інтегрованим середовищем ServBay для створення, налаштування та запуску сайту на VitePress з нуля, включаючи налаштування реверс-проксі для сервера розробки та обслуговування статичних файлів у production.

Що таке VitePress?

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

Основні переваги та можливості VitePress

• Блискавичний ритм розробки: завдяки гарячій заміні модулів (HMR) від Vite — зміни відображаються у браузері майже миттєво, забезпечуючи продуктивний процес.
• Потужність Vue: можна безпосередньо використовувати Vue-компоненти у Markdown-файлах, що значно підвищує інтерктивність та виразність документації.
• Простота: мінімальна конфігурація, "з коробки", ідеальне середовище для зосередження на наповненні контентом.
• Висока продуктивність: вихідний статичний сайт — компактний та швидкий, з плавною SPA-навігацією завдяки вбудованому клієнтському роутеру.
• SEO-оптимізація: генерація HTML-структури, сприятливої для індексації пошуковими системами, підтримка кастомних тегів в head.
• Потужний Markdown: підтримка CommonMark, GitHub Flavored Markdown (GFM) та додаткові синтаксичні можливості.

Завдяки VitePress розробники можуть просто й швидко створювати високоякісні та продуктивні документаційні ресурси.

Створення та запуск проекту VitePress у ServBay

ServBay пропонує зручний спосіб керувати версіями Node.js і налаштовувати веб-сервер для вашого VitePress-проекту — як у режимі розробки, так і для продакшену.

Передумови

Перед стартом переконайтеся, що виконали наведені нижче дії:

1. Встановили ServBay: На вашому macOS уже має бути інстальовано ServBay. Якщо ще ні — скористайтеся інструкцією з встановлення ServBay.
2. Встановлено Node.js: Переконайтеся, що вибрана вами версія Node.js встановлена та активна у ServBay. Це можна зробити на сторінці "Пакети" в панелі керування ServBay: Використання Node.js.

Ініціалізація проекту VitePress

1. Створення проектної папки

   Відкрийте термінал. Рекомендується створити проект у корені веб-сайтів ServBay — /Applications/ServBay/www — це спростить подальше налаштування ServBay.

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. Встановлення VitePress та ініціалізація проекту

   Перебуваючи у теці проекту servbay-vitepress-app, встановіть VitePress як дев-залежність через npm або yarn, і запустіть команду ініціалізації:

   npm add -D vitepress
   npx vitepress init

   або через Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Під час ініціалізації вас попросять вказати ключові параметри: назву сайту, опис і т.д. Дотримуйтеся підказок:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Шлях до папки з документацією, залиште за замовчуванням і натисніть Enter
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Введіть назву сайту, наприклад ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Введіть опис сайту
    │
    ◇  Theme:
    │  Default Theme # Тематика — виберіть стандартну
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Додавати TypeScript до конфігурації — на ваш розсуд
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Додавати скрипти до package.json — рекомендується Yes
    │
    └  Done! Now run npm run docs:dev and start writing.

   Після цього у каталозі проекту з’явиться папка docs, основна конфігурація (.vitepress) та кілька прикладів сторінок (index.md, guide/index.md тощо). Також package.json отримає скрипти типу docs:dev і docs:build.

Редагування контенту проекту VitePress

1. Редагування головної сторінки

   Основний файл головної сторінки — docs/index.md. Відкрийте його будь-яким текстовим редактором і доповніть/замініть вміст, наприклад:

   # Hello ServBay!
   
   Ласкаво просимо до запуску вашого документаційного сайту VitePress за допомогою ServBay.
   
   Це локальний демонстраційний сайт, створений на VitePress та обслуговується сервісом ServBay.

Запуск у режимі розробки

Для розробки сайту VitePress зазвичай використовується вбудований дев-сервер з підтримкою гарячого оновлення. Далі налаштуйте реверс-проксі від ServBay для доступу до серверу розробки через власний домен із підтримкою SSL.

1. Запуск дев-сервера VitePress

   У терміналі (у каталозі /Applications/ServBay/www/servbay-vitepress-app) введіть команду для старту серверу, зазначаючи вільний порт (наприклад, 8585):

   npm run docs:dev -- --port 8585

   або через Yarn:

   yarn docs:dev --port 8585

   Сервер запуститься і буде доступний локально, наприклад, за адресою http://localhost:8585.

2. Налаштування сайту ServBay (реверс-проксі)

   У панелі керування ServBay відкрийте розділ "Сайти" та додайте нову конфігурацію:

   • Ім’я: наприклад, Сайт розробки VitePress.
   • Домен: локальний домен для тестування, рекомендовано використовувати суфікс .servbay.demo, наприклад vitepress-dev.servbay.demo.
   • Тип сайту: виберіть Реверс-проксі.
   • IP: 127.0.0.1 (локальний хост).
   • Порт: порт, вказаний раніше, тобто 8585.

   Збережіть та застосуйте зміни. ServBay автоматично налаштує веб-сервер (Caddy чи Nginx), щоб усі звернення до https://vitepress-dev.servbay.demo переспрямовувалися на http://127.0.0.1:8585.

3. Відкриття сайту розробки у браузері

   Тепер перейдіть у браузері за адресою https://vitepress-dev.servbay.demo. Ви побачите вміст, що обслуговується dev-сервером VitePress. Завдяки ServBay отримуєте використання власного домену й автоматичний SSL-сертифікат (ServBay User CA), що забезпечує захищений HTTPS-доступ.

Побудова production-версії

Коли документація готова до релізу — потрібно зібрати production-версію сайту.

1. Збірка production-версії

   У каталозі проекту /Applications/ServBay/www/servbay-vitepress-app зберіть статичний билд:

   npm run docs:build

   або через Yarn:

   yarn docs:build

   Система згенерує оптимізовані статичні HTML-, CSS-, JS-файли у теці docs/.vitepress/dist.

2. Налаштування сайту ServBay (статичний сайт)

   Production-версія сайту — це набір статичних файлів, які можна напряму обслуговувати через ServBay.

   Знову у ServBay, на сторінці "Сайти", додайте нову конфігурацію:

   • Ім’я: наприклад, Production-сайт VitePress.
   • Домен: бажаний локальний домен для production, наприклад vitepress-prod.servbay.demo.
   • Тип сайту: Статичний.
   • Коренева тека: абсолютний шлях до зібраних файлів: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Збережіть і застосуйте зміни. ServBay налаштує веб-сервер для прямої роздачі статичного контенту з вказаної теки.

3. Перегляд production-сайту

   Тепер ви можете перейти за вашим доменом https://vitepress-prod.servbay.demo і побачити production-версію сайту. ServBay також забезпечує кастомний домен та видає автоматизований SSL-сертифікат.

Підтримка clean URLs (cleanUrls: true)

VitePress підтримує опцію cleanUrls: true, яка дозволяє прибрати розширення .html у посиланнях. Для коректної роботи серверу при таких запитах необхідно додатково налаштувати Caddy або Nginx.

ServBay використовує Caddy або Nginx для обслуговування сайтів. Як приклад, наведено Caddy-конфігурацію із директивою try_files, яка підбирає відповідний файл згідно з url (без/з .html/index.html).

1. Увімкнення cleanUrls у VitePress

   Змініть конфігураційний файл VitePress (docs/.vitepress/config.mts або docs/.vitepress/config.ts), вказавши параметр cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... інші налаштування
     cleanUrls: true, // Увімкнути clean URLs
     // ... інші налаштування
   })

   Знову запустіть збірку production: npm run docs:build.

2. Налаштування ServBay (з кастомним Caddy-конфігом)

   У панелі ServBay у розділі "Сайти" знайдіть потрібний домен (наприклад, vitepress-prod.servbay.demo):

   • Натисніть "Редагувати".
   • Активуйте опцію Користувацька конфігурація.
   • У полі Caddy-конфігурація вставте адаптований фрагмент, підмінивши servbay-vitepress-test.prod на ваш домен, а шлях — на фактичний до папки production-білду:

   # Замініть на реальний домен, напр. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Увімкнути Brotli (zstd) та Gzip для оптимізації швидкості
       encode zstd gzip
   
       # Підключити дефолтні логи ServBay
       import set-log vitepress-cleanurl.servbay.demo
   
       # Автоматична робота зі внутрішнім SSL ServBay
       tls internal
   
       # Головне: спроба знайти потрібний файл
       # 1. Пряма відповідність (e.g., /about -> /about)
       # 2. Папка з index.html (/guide/ -> /guide/index.html)
       # 3. Файл із суфіксом .html (/about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Коренева директорія сайту
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Ввімкнути сервіс статичних файлів
       file_server
   }

   Збережіть та застосуйте зміни.

3. Тестування clean URLs

   Спробуйте перейти на ваш домен (наприклад, https://vitepress-cleanurl.servbay.demo). Для сторінок із чистими URL-адресами достатньо писати /about замість /about.html — сервер знайде потрібний файл автоматично.

Висновок

Дотримуючись цієї інструкції, ви зможете швидко розгорнути, розробляти та деплоїти документаційний сайт на VitePress у середовищі ServBay. ServBay значно спрощує керування Node.js та конфігурацією локального веб-сервера — незалежно від того, чи потрібен вам реверс-проксі для розробки, чи роздача production-білду як статичних файлів. Ви також отримуєте автоматичну підтримку кастомних доменів і SSL-сертифікатів.

Використовуючи потужний тандем ServBay і VitePress, ви зможете ефективно створювати сучасну високоякісну технічну документацію!