Создание и запуск проекта VitePress с помощью ServBay

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

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

В этом руководстве вы узнаете, как использовать интегрированную среду ServBay для создания, настройки и запуска проекта VitePress с нуля, включая настройку обратного прокси для development-сервера и статическую файловую службу для production-сборки.

Что такое VitePress?

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

Основные преимущества и особенности VitePress

• Мгновенная разработка: благодаря горячей замене модулей (HMR) в Vite любые изменения отображаются в браузере почти моментально — быстрый итерационный цикл.
• Работает на Vue: поддержка Vue-компонентов прямо в Markdown-файлах усиливает интерактивность и выразительность документации.
• Простота: минимальные настройки, готов к работе из коробки — сосредоточьтесь на содержимом.
• Высокая производительность: небольшие размеры итоговых файлов, быстрая загрузка, современный клиентский роутер для плавной SPA-экспириенса.
• SEO-оптимизация: чистая HTML-разметка, легко индексируется поисковиками; поддержка пользовательских head-тегов.
• Улучшенный Markdown: совместим с CommonMark и GFM, плюс дополнительные возможности.

С VitePress можно быстро создать качественный и производительный сайт документации.

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

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

Предварительные требования

Перед началом убедитесь, что выполнены следующие шаги:

1. Установлен ServBay: ServBay должен быть инсталлирован на вашем компьютере. Если нет — следуйте инструкции по установке ServBay.
2. Установлен пакет Node.js: В интерфейсе ServBay убедитесь, что активирована нужная версия Node.js. Управление доступно на странице “Пакеты”. Подробнее: Использование 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 в dev-dependencies и выполните инициализацию:

   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 # настройте по предпочтению
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # рекомендуем выбрать 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!
   
   Добро пожаловать в ServBay — запустите свой сайт документации VitePress быстро и просто.
   
   Это демонстрационный сайт VitePress, который обслуживается с помощью ServBay.

Переход в режим разработки

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

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

   В терминале перейдите в корневую папку проекта (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app) и запустите сервер на выбранном порту (например, 8585):

   npm run docs:dev -- --port 8585

   или

   yarn docs:dev --port 8585

   После запуска dev-сервер будет доступен по локальному адресу (http://localhost:8585).

2. Настройка сайта ServBay (reverse proxy)

   В панели ServBay откройте страницу “Сайты” и добавьте новую конфигурацию:

   • Имя: например, VitePress сервера разработки.
   • Домен: выберите локальный домен для доступа, например vitepress-dev.servbay.demo.
   • Тип сайта: выберите Reverse Proxy.
   • IP: 127.0.0.1 (localhost).
   • Порт: порт dev-сервера, например 8585.

   Сохраните и примените изменения. ServBay настроит proxy так, что запросы на https://vitepress-dev.servbay.demo будут перенаправляться на http://127.0.0.1:8585.

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

   Откройте в браузере https://vitepress-dev.servbay.demo. Вы увидите ваш сайт VitePress. ServBay автоматически выдаёт SSL-сертификат User CA для HTTPS.

Сборка production-версии

После завершения подготовки документации её можно собрать в виде оптимизированных статических файлов.

1. Сборка production-версии

   Перейдите в корневую папку проекта (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app) и выполните:

   npm run docs:build

   или

   yarn docs:build

   После сборки статические файлы окажутся в docs/.vitepress/dist.

2. Настройка сайта ServBay (статические файлы)

   Сервировать production-версию удобно через статическую файловую службу ServBay.

   В панели ServBay откройте “Сайты” и добавьте новую конфигурацию:

   • Имя: например, VitePress production-сайт.
   • Домен: например, vitepress-prod.servbay.demo.
   • Тип сайта: Static.
   • Корневая папка сайта:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   Примените изменения. Сервер будет отдавать статические файлы напрямую.

3. Доступ к production-сайту

   Откройте в браузере https://vitepress-prod.servbay.demo — появится production-версия документации, с удобным собственным доменом и SSL.

Работа в режиме cleanUrls (cleanUrls: true)

VitePress поддерживает cleanUrls: true, что убирает расширение .html в ссылках (например, /guide/ вместо /guide/index.html). Для корректной работы нужна специальная конфигурация веб-сервера.

ServBay использует Caddy или Nginx. Ниже пример настройки для Caddy с директивой try_files, чтобы автоматически искать нужные файлы:

1. Включите cleanUrls в конфиге VitePress

   В файле конфигурации (docs/.vitepress/config.mts или docs/.vitepress/config.ts) добавьте:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... остальная конфигурация
     cleanUrls: true, // включить cleanUrls
     // ... остальная конфигурация
   })

   После изменений пересоберите проект: npm run docs:build.

2. Кастомная настройка сайта ServBay (Caddy)

   В панели ServBay откройте ваш production-сайт (например, vitepress-prod.servbay.demo):

   • Нажмите “Редактировать”.
   • Отметьте “Custom config”.
   • В поле для конфигурации Caddy вставьте настройки ниже (замените домен и путь на свои):
     • 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 ServBay User CA
       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. Доступ к сайту с чистыми URL

   Теперь ваш сайт будет работать с URL без .html, например, страницу about.html можно открыть по адресу https://vitepress-cleanurl.servbay.demo/about.

Итог

Следуя этому гиду, вы сможете легко создать, разработать и развернуть сайт документации на VitePress в окружении ServBay. ServBay упрощает управление Node.js и настройку веб-сервера, помогает быстро организовать reverse proxy для разработки или статическую публикацию, а также автоматически выдает SSL и домены.

Используйте мощное сочетание ServBay и VitePress для быстрой и удобной работы с технической документацией на вашем локальном компьютере.