Создание и запуск проекта 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-файлов, значительно расширяя возможности и интерактивность документации.
• Простота и удобство: Легко настраивается, работает "из коробки", позволяет сосредоточиться на контенте.
• Высокая производительность: Генерирует компактные статические файлы с быстрой загрузкой и реализует плавную навигацию как одностраничное приложение.
• Оптимизировано для SEO: HTML-структура дружелюбна для поисковых систем, также поддерживаются настраиваемые теги head.
• Улучшенный Markdown: Поддержка стандартов CommonMark и GitHub Flavored Markdown (GFM), а также дополнительных синтаксических возможностей.

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

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

ServBay предлагает простой способ управления версиями Node.js и настройки веб-сервера под задачи вашего VitePress-проекта — будь то локальный сервер для разработки или хостинг статических файлов для продакшна.

Необходимые условия

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

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

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

Редактирование содержимого проекта VitePress

1. Редактирование главной страницы

   Домашняя страница по умолчанию — это файл docs/index.md. Откройте его в любом текстовом редакторе и отредактируйте, например так:

   # Привет, ServBay!
   
   Добро пожаловать! С помощью ServBay вы можете запускать свой сайт документации на VitePress.
   
   Это локальный демонстрационный сайт, созданный на 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 — виден результат работы сервера VitePress для разработки. Благодаря ServBay вы получили не только локальный домен, но и автоматический SSL-сертификат для безопасного HTTPS-соединения.

Сборка продакшн-версии

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

1. Построение продакшн-версии

   В терминале, в папке /Applications/ServBay/www/servbay-vitepress-app, выполните команду сборки:

   npm run docs:build

   Или через Yarn:

   yarn docs:build

   В процессе сборки ваш Markdown и Vue-компоненты будут собраны в оптимизированные статические HTML, CSS и JS файлы. По умолчанию результат будет в папке docs/.vitepress/dist в вашем проекте.

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

   Готовая версия сайта — это обычный набор статических файлов, поэтому удобно воспользоваться статическим сервисом ServBay.

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

   • Имя: Например, VitePress сайт — Продакшн.
   • Домен: Локальный домен, например, vitepress-prod.servbay.demo.
   • Тип сайта: Выберите Статический.
   • Корневая папка сайта: Укажите абсолютный путь к папке с собранными статическими файлами: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Сохраните и примените конфигурацию. ServBay настроит веб-сервер для обслуживания этих файлов напрямую.

3. Проверьте продакшн-версию

   В браузере откройте https://vitepress-prod.servbay.demo — вы увидите собранную версию вашего сайта на VitePress. Домен и SSL также настроены автоматически через ServBay.

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

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

ServBay использует в качестве веб-сервера Caddy или Nginx. Ниже — пример настройки Caddy через директиву try_files, чтобы последовательно искать файл по разным вариантам (без расширения, как индекс, с .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, // Включить чистые URLs
     // ... прочие настройки
   })

   Пересоберите проект для продакшн-версии командой npm run docs:build.

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

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

   • Нажмите "Редактировать".
   • Активируйте опцию Пользовательская конфигурация.
   • В поле для конфигурации Caddy вставьте следующий пример. Не забудьте заменить servbay-vitepress-test.prod на свой домен, а путь /Applications/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
       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
   
       # Указываем корневую папку сайта
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Включаем сервис статических файлов
       file_server
   }

   Сохраните и примените изменения.

3. Проверьте сайт в режиме Clean URLs

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

Заключение

В этом руководстве вы научились создавать, разрабатывать и публиковать сайты документации на VitePress в среде ServBay. ServBay заметно облегчает управление Node.js-окружением и настройку локального веб-сервера — будь то для разработки с обратным проксированием или для публикации через сервис статических файлов, а также автоматизирует выдачу кастомных доменов и SSL-сертификатов.

Благодаря мощности и удобству связки ServBay + VitePress вы сможете быстро и профессионально создавать современные технические документы, не тратя время на ручные настройки серверов.