Установка и настройка Jigsaw в среде ServBay

Обзор

В этом документе подробно рассказывается, как установить и настроить генератор статических сайтов Jigsaw в мощной локальной среде веб-разработки ServBay. ServBay обеспечивает единое интегрированное окружение для стека технологий (таких как PHP, Node.js и др.), что существенно облегчает процесс создания проектов на Jigsaw. Благодаря ServBay, вы легко настроите локальный домен, HTTPS и современный веб-сервер для вашего Jigsaw-проекта, чтобы сосредоточиться на разработке контента сайта.

Что такое Jigsaw?

Jigsaw — генератор статических сайтов, построенный на компонентах Laravel и разработанный компанией Tighten. Он использует возможности и гибкость шаблонизатора Laravel Blade, а также Markdown-файлы для создания чистых статических HTML-сайтов. Jigsaw отлично подходит для создания сайтов-документаций, блогов, лендингов или других сайтов, которые не требуют базы данных и серверной обработки. Основные преимущества:

• Использование знакомых инструментов: Если вы знакомы с Laravel или шаблонами Blade, освоить Jigsaw будет очень просто.
• Высокая производительность и безопасность: Генерируемые статические сайты загружаются быстро и защищены за счет отсутствия серверных вычислений.
• Гибкие шаблоны: С Blade вы можете создавать сложные макеты и компоненты.
• Markdown-поддержка: Писать контент легко и удобно.

Типовые сценарии использования

Jigsaw отлично решает такие задачи, как:

• Документационные и API-сайты проектов
• Персональные блоги или сайты для публикации технических материалов
• Маркетинговые лендинги для компаний или продуктов
• Малые сайты-визитки
• Любые сайты с высокими требованиями к скорости и безопасности, где контент редко изменяется

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

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

1. ServBay установлен и запущен: Для работы необходима установка и запуск ServBay на системе macOS. Необходимые инструменты PHP, Composer и Node.js/npm уже включены в ServBay по умолчанию.
2. Навыки работы с терминалом: Необходимо уметь выполнять команды в терминале.
3. Базовое понимание работы с Composer и npm: Jigsaw устанавливается через Composer, а сборка front-end ресурсов производится с помощью npm.

Пошаговое руководство по установке и настройке

В этом разделе описан полный процесс установки и конфигурации проекта Jigsaw в среде ServBay.

Шаг 1: Создание директории для проекта

Откройте терминал и перейдите в рекомендованную корневую папку сайтов ServBay /Applications/ServBay/www, создав в ней отдельную папку для вашего Jigsaw-проекта.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

В данном примере проект размещается в директории servbay-jigsaw-demo, где и будут лежать все рабочие файлы.

Шаг 2: Создание Jigsaw-проекта с помощью Composer

ServBay поставляется с предустановленным Composer — вы можете использовать команду composer прямо в терминале. Находясь в созданной директории /Applications/ServBay/www/servbay-jigsaw-demo, выполните команду:

composer create-project tightenco/jigsaw .

Эта команда загрузит последнюю версию Jigsaw и все необходимые PHP-зависимости в текущую папку (.). Обратите внимание на точку в конце — она указывает Composer использовать текущую папку (без создания подпапки jigsaw).

Шаг 3: Настройка сайта в ServBay

Чтобы открыть ваш Jigsaw-сайт в браузере, нужно создать локальный сайт в интерфейсе ServBay.

1. Откройте интерфейс ServBay: Дважды кликните на иконку ServBay или выберите её в меню.
2. Перейдите во вкладку «Сайты»: В левой панели кликните по закладке «Сайты».
3. Добавьте новый сайт: Нажмите кнопку «+» внизу экрана и выберите пункт «Добавить сайт».
4. Заполните данные о сайте:
   • Имя (Name): Введите понятное название, например, ServBay Jigsaw Demo.
   • Домен (Domain): Пропишите доменное имя для локального доступа. Рекомендуется использовать окончание .servbay.demo, например, jigsaw-demo.servbay.demo — ServBay автоматически направит такой домен на ваш компьютер.
   • Тип сайта (Site Type): Выберите PHP, так как процесс сборки Jigsaw требует PHP.
   • Версия PHP (PHP Version): Укажите подходящую версию PHP, установленную в ServBay (рекомендуется использовать свежую стабильную).
   • Корневая директория сайта (Site Root): Очень важно! После сборки Jigsaw складывает статические файлы в папку build_local в корне проекта. Поэтому корневую директорию сайта укажите как: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Сохраните и примените настройки: После заполнения всех полей нажмите «Сохранить». ServBay предложит применить изменения — подтвердите действие. ServBay автоматически обновит конфигурацию веб-сервера (Caddy или Nginx) и настроит HTTPS.

Шаг 4: Установка front-end зависимостей

Jigsaw-проекты обычно используют npm для управления и сборки фронтенд-ресурсов (например, SASS, JS, и др.). В среде ServBay Node.js и npm доступны из коробки.

Выполните в папке проекта (/Applications/ServBay/www/servbay-jigsaw-demo):

npm install

Это установит все необходимые npm-модули, перечисленные в package.json.

Шаг 5: Сборка сайта Jigsaw

Когда все зависимости установлены, выполните команду для сборки статических файлов сайта:

./vendor/bin/jigsaw build

Данная команда:

1. Обрабатывает Markdown-файлы и Blade-шаблоны из папки source.
2. Запускает задачи сборки из webpack.mix.js (если, после установки npm, используется Laravel Mix).
3. Сохраняет готовые HTML, CSS, JS и статические ресурсы в папку build_local.

Шаг 6: Просмотр сайта

Теперь сгенерированные статические файлы сайта находятся в /Applications/ServBay/www/servbay-jigsaw-demo/build_local. Так как корневая директория сайта в ServBay уже на неё указывает, вы можете сразу открыть сайт в браузере по заданному ранее домену.

Откройте браузер и перейдите по адресу, который указывали при настройке сайта, например, https://jigsaw-demo.servbay.demo. ServBay автоматически подключит HTTPS-сертификат (через своё CA), и вы увидите стартовую страницу Jigsaw.

Кастомизация и разработка

Поздравляем, базовое окружение запущено! Теперь вы можете адаптировать контент и внешний вид своего сайта на Jigsaw.

Редактирование контента и шаблонов

• Исходный код сайта хранится в папке source в корне проекта.
• HTML-структура и компоненты на Blade-шаблонах — папки source/_layouts, source/_partials и др.
• Контент страниц обычно пишется на Markdown и лежит в source или дочерних папках (source/index.md, source/about.md и т.д.).
• Блог-посты располагаются в source/_posts — файл для поста имеет формат имени YYYY-MM-DD-slug.md.

Добавление новых страниц/статей

Чтобы добавить новую страницу или пост в блог, просто создайте новый Markdown-файл в source или соответствующей подпапке (source/_posts).

Например, создать файл source/about.md:

---
title: "О нас"
description: "Подробнее о проекте ServBay Jigsaw Demo"
---

# О нас

Это пример страницы «О нас», созданной с помощью Jigsaw.

Здесь вы можете разместить представление компании, описание команды и другую информацию.

Кастомные стили и скрипты

В Jigsaw-проектах обычно используется Laravel Mix (файл webpack.mix.js) для сборки CSS и JS файлов:

• SASS/SCSS-файлы для стилей — папка source/_assets/sass
• JavaScript-файлы — папка source/_assets/js

Для сборки этих ресурсов используйте npm-скрипты прямо в корневой директории проекта:

• npm run dev: Собирает ресурсы для разработки (с картами исходников, не минифицировано).
• npm run watch: Сборка для разработки плюс автоматическая пересборка при изменениях файлов.
• npm run prod: Сборка для «боевого» режима с минификацией и оптимизациями.

Например, после редактирования файла source/_assets/sass/main.scss выполните команду npm run dev или npm run watch, чтобы генерация CSS прошла заново.

Повторная сборка сайта

Важно: После каждого изменения в Markdown-файлах или Blade-шаблонах в папке source обязательно запускайте сборку:

./vendor/bin/jigsaw build

При изменениях frontend-ассетов (SASS, JS) используйте npm run dev или npm run watch. В большинстве проектов Jigsaw команда build также запускает Mix, но бывает полезно понимать этот процесс отдельно во избежание ошибок.

Важные замечания

• Папка сборки: По умолчанию Jigsaw собирает сайт в каталоги build_local (для разработки) и build_production (для production). Убедитесь, что ServBay-сайт ссылается на нужную папку (обычно для разработки — build_local).
• Веб-сервер: ServBay использует Caddy или Nginx для обслуживания статических файлов из папки build_local — это быстро и эффективно. Не используйте встроенную команду Jigsaw jigsaw serve (она предназначена лишь для быстрого предварительного просмотра и не столь мощная, как полноценный сервер ServBay).
• HTTPS: ServBay автоматически настраивает HTTPS для доменов на .servbay.demo и выпускает сертификаты через свой CA. При необходимости импортируйте корневой сертификат ServBay User CA в доверенные системы для избавления от предупреждений в браузере.
• Чистая сборка: Если возникает нестандартная ошибка при сборке сайта, попробуйте выполнить команду для чистой предсборки: ./vendor/bin/jigsaw build --clean.

Часто задаваемые вопросы (FAQ)

В: Я изменил Markdown-файл, почему изменение не видно в браузере?

О: После редактирования контента или шаблона необходимо выполнить команду ./vendor/bin/jigsaw build в терминале для пересборки сайта.

В: Я изменил SCSS-файл, а стиль не обновился?

О: После изменений во frontend-файлах выполните команду npm run dev или npm run watch из корня проекта для повторной сборки ассетов.

В: При попытке зайти по локальному домену вижу ошибку “не удается найти сайт” или “файл не найден”?

О: Проверьте следующее:

1. ServBay действительно запущен.
2. В настройках сайта в ServBay правильно указан домен и корневая папка (/Applications/ServBay/www/servbay-jigsaw-demo/build_local).
3. Вы успешно выполнили ./vendor/bin/jigsaw build и в build_local созданы все нужные файлы (например, index.html).

В: Как можно разместить (деплоить) сайт на Jigsaw?

О: Jigsaw формирует статический набор файлов. Типовая схема публикации:

1. Выполните команду ./vendor/bin/jigsaw build production для production-сборки и оптимизации.
2. Загрузите все файлы из папки build_production на любой сервис, который поддерживает статический хостинг (Netlify, Vercel, GitHub Pages, различные облачные хранилища и т.п.).

Заключение

С помощью ServBay процесс установки и конфигурации Jigsaw на macOS становится простым и быстрым. ServBay предоставляет все необходимые инструменты (PHP, Composer, Node.js, npm) и гибко настраиваемый локальный веб-сервер. Следуя этому руководству, вы сможете в кратчайшие сроки запустить свой Jigsaw-проект и использовать все преимущества среды ServBay для оптимальной локальной разработки.