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

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

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

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

Що таке VitePress?

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

Головні переваги та особливості VitePress

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

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

Створення та запуск VitePress-проєкту за допомогою ServBay

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

Перед початком роботи

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

1. Встановили ServBay: ServBay має бути інстальований у вашій системі. Якщо ви цього ще не зробили, ознайомтеся з інструкцією з встановлення ServBay.
2. Встановили пакет Node.js: У ServBay переконайтесь, що обрана та активована потрібна версія Node.js. Керувати цим можна на сторінці "Software Packages" у контрольній панелі ServBay. Детальніше: Використання Node.js.

Створення нового проєкту VitePress

1. Ініціалізуйте директорію проєкту

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

   macOS:

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

   Windows:

   cd C:\ServBay\www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. Встановіть VitePress та ініціалізуйте конфігурацію

   У каталозі servbay-vitepress-app встановіть VitePress як залежність для розробки та запустіть команду ініціалізації.

   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 — рекомендується
    │
    └  Done! Now run npm run docs:dev and start writing.

   Після ініціалізації, в папці servbay-vitepress-app з’явиться директорія docs з файлом налаштувань (.vitepress) і тестовими сторінками (index.md, guide/index.md та ін.). package.json також буде оновлено, додано скрипти docs:dev і docs:build.

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

1. Змініть контент головної сторінки

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

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

Перехід у режим розробки

Зазвичай в процесі створення сайту на VitePress використовується вбудований сервер розробки, що підтримує гаряче оновлення сторінки. Далі налаштуємо зворотний проксі ServBay для доступу через власний домен і захищене (SSL) з'єднання.

1. Запустіть сервер розробки VitePress

   Переконайтесь, що ви знаходитесь у корені проєкту (/Applications/ServBay/www/servbay-vitepress-app для macOS, C:\ServBay\www\servbay-vitepress-app для Windows). Запустіть сервер, вказавши порт (наприклад, 8585):

   npm run docs:dev -- --port 8585

   Або через Yarn:

   yarn docs:dev --port 8585

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

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

   Відкрийте панель ServBay, перейдіть на сторінку "Сайти". Додайте нову конфігурацію:

   • Назва: Вкажіть назву, наприклад Сайт розробки VitePress.
   • Домен: Введіть бажаний локальний домен, наприклад vitepress-dev.servbay.demo.
   • Тип сайту: Оберіть Зворотний проксі.
   • IP: Введіть 127.0.0.1 (локальний хост).
   • Порт: Той порт, який ви вибрали у кроці 1, наприклад 8585.

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

3. Доступ до сайту розробки

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

Збірка продакшн-версії

Коли контент готовий до публікації, потрібно згенерувати оптимізовану статичну версію сайту.

1. Збірка продакшн-версії

   В терміналі перейдіть у корінь проєкту (/Applications/ServBay/www/servbay-vitepress-app для macOS, C:\ServBay\www\servbay-vitepress-app для Windows) та виконайте команду:

   npm run docs:build

   Або через Yarn:

   yarn docs:build

   У результаті ваші Markdown-файли, компоненти Vue та інші ресурси будуть скомпільовані у оптимізовані статичні файли — HTML, CSS, JavaScript — у каталозі docs/.vitepress/dist.

2. Налаштування сайту у ServBay (статична подача файлів)

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

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

   • Назва: Наприклад, Сайт продакшн VitePress.
   • Домен: Вкажіть локальний домен, наприклад vitepress-prod.servbay.demo.
   • Тип сайту: Оберіть Статичний.
   • Кореневий каталог сайту: Шлях до каталогу зі статичними файлами:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

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

3. Доступ до продакшн-сайту

   Тепер ви можете перейти за вашою локальною адресою, наприклад https://vitepress-prod.servbay.demo, та побачити готовий сайт. ServBay також забезпечить роботу HTTPS через автоматичне SSL-шифрування й власний домен.

Робота у режимі "чистих" URL (cleanUrls: true)

VitePress підтримує налаштування cleanUrls: true, яке дозволяє використовувати посилання без .html розширення (наприклад, /guide/ замість /guide/index.html чи /about замість /about.html). Щоб веб-сервер правильно обробляв такі запити, потрібно зробити додаткову конфігурацію.

ServBay використовує Caddy або Nginx для веб-сервера. Ось приклад для Caddy з директивою try_files, яка шукає відповідний файл (.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({
     // ... other config
     cleanUrls: true, // Увімкнути clean URLs
     // ... other config
   })

   Перезапустіть збірку продакшн-версії: npm run docs:build.

2. Налаштуйте сайт ServBay (кастомна конфігурація Caddy)

   Перейдіть на сторінку "Сайти" у ServBay, знайдіть вашу продакшн-конфігурацію (наприклад, vitepress-prod.servbay.demo):

   • Натисніть "Редагувати".
   • Відмітьте опцію "Кастомна конфігурація".
   • У полі для конфігурації Caddy вставте та адаптуйте наступний код, замінивши servbay-vitepress-test.prod на ваш реальний домен і шлях до статичних файлів:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

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

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

3. Доступ до сайту з clean URL

   Відтепер за вашим доменом, наприклад https://vitepress-cleanurl.servbay.demo, можна звертатись по адресах без .html. Наприклад, для сторінки about.html — достатньо перейти на https://vitepress-cleanurl.servbay.demo/about.

Підсумок

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

Завдяки потужному поєднанню ServBay і VitePress ви маєте змогу ще ефективніше створювати й підтримувати якісну технічну документацію.