Сборка статического сайта

Сборка максимально совместима с подходами HTML Academy для совместимости с опытом её студентов:

• Следование кодгайду Академии.
• Соответствие критериям защиты проекта на втором интенсиве по вёрстке. То есть, можно использовать на интенсиве.

Отличия (и их причины):

• Поддержка нескольких режимов (собственно сборка, разработка и тестирование):
  • Скрипт тестирования запускается перед коммитом, не позволяя закоммитить плохой код.
  • В режимах разработки и тестирования собранные файлы складываются в каталог dev:
    • Позволяет сохранить крайний успешный билд.
    • Если ваши процессы вынуждены следовать антипаттерну запушивания каталога build/, исключён вариант попадания туда разработческой версии, да и git diff в этом случае не будет показывать лишних изменений при запуске режима разработки.
  • В режиме сборки отключено создание sourcemaps.
  • Задачи gulp гибко меняют поведение в зависимости от режима работы сборки.
  • В шаблонизатор разметки, препроцессор стилей интегрированы предикаты isDev и isTest.
• Шаблонизатор разметки twig:
  • Шаблонизатор как таковой упрощает разработку:
    • Повторяющиеся части страниц не приходится писать несколько раз.
    • При должной связке с данными код можно напрямую подключать к бэкенду (PHP, node) без перенатяжки на движок.
  • Данный шаблонизатор имеет нулевой порог входа: обычный HTML-код - это уже twig-код. Можно изучать шаблонизцию постепенно.
• Удалён gulp-plumber, неактуальный для текущей версии gulp, а иногда даже роняющий сборку в этой версии.
• "Живые" линтеры с выводом сообщений в терминал при изменении файлов:
  • Линтеры многих редакторов не видят ошибок в закрытых файлах.
  • Видеть информацию о проекте удобнее в одном месте - в открытом в нижней части редактора терминале.
  • К завершению текущих работ может накопиться много ошибок, неожиданно продлевающих рабочую смену.
  • Выводя мгновенно ошибки, сборка выполняет функцию обучения красивому коду.
• Добавлен линтер порядка свойств по кодгайду Академии, а также кастомизация набора разрешенных @-директив в SCSS.
• libsquosh заменён на imagemin:
  • libsquosh диктует нам оставаться на несвежей версии node.
  • libsquosh в несколько раз медленнее imagemin.
  • При некоторых аппаратных конфигурациях он конфликтует с dart-sass.
  • imagemin позволяет обработать все форматы в одной задаче.
• Для сборки и оптимизации модульных скриптов добавлен esbuild - один из самых быстрых бандлеров js.
• Статические файлы перенесены в каталог static/:
  • Минимизация файловых операций: файлы лишь однократно копируются в build/ при сборке продукта.
  • Шрифты, фавиконки и прочие однократно изготавливаемые файлы не мешают анализу исходников.
  • Если необходимо предварительно оптимизировать изображения вручную (ошибка или неоптимальность автооптимизации), файлы можно хранить в static/img.
  • Если вы не используете шаблонизатор разметки - здесь можно хранить html-файлы, изменение которых будет перезагружать браузер.
• Изображения в режиме разработки видны прямо из source/:
  • Отсутствует необходимость их копирования в каталог сборки при каждом изменении.
  • webp-изображения в режиме разработки создаются точечно.
• Добавлен каталог source/pixelperfect с готовым к использованию скриптом pixelperfect-tool:
  • Если в данный каталог положить изображения вида <имя страницы без .html>-<числовое значение брейкпоинта>.<расширение изображения> и подключить скрипт по пути pixelperfect/pixelperfect.min.js, переключение изображений между страницами и брейкпоинтами будет происходить автоматически
  • При сборке продукта подключение скрипта удаляется из разметки, каталог pixelperfect не попадает в сборку.
• Добавлен гитхаб-экшн - функционал по проверке и деплою проекта со стороны github:
  • При каждом пуше или пулреквесте в главную ветку вашего репозитория на стороне github будет запускаться npm test, в случае успеха - npm run build. Собранный продукт будет опубликован в удаленную ветку gh-pages для публикации.

Поддерживаемые команды

• npm ci - установка пакетов, обязательно в начале работы.
• npm start - запуск проекта в режиме разработки со слежением за файлами и перезагрузкой страницы в браузере. Предварительная сборка выполняется в каталог dev/.
• npm test - запуск линтеров и валидаторов.
• npm run build - запуск сборки готового проекта в папку build.

Структура

• .github/workflows/*.yml - экшны гитхаба. Не путать со служебным каталогом .git/!
• build/ - каталог полноценной сборки готового продукта. Очищается перед каждой сборкой.
• dev/ - каталог для собираемых файлов, которые браузер использует в режиме разработки.
• source/ - каталог для исходных кодов и вспомогательных файлов разработки:
  • source/data/ - каталог для хранения данных, пробрасываемых в шаблонизатор разметки или в клиентские скрипты, в произвольном формате.
    • source/data/index.js - болванка скрипта для управления этими данными. Создайте здесь свой бэкенд!
  • source/img/ - каталог для неоптимизированных изображений. В режиме разработки видны из текущего положения (с учетом подпапок), в режиме сборки весь каталог копируется в build/.
  • source/js - каталог для скриптов. Каждый файл из этого каталога (не из подкаталогов) будет собран в единый бандл build/js/*.min.js со всем связанными импортами (хранимыми в подкаталогах).
  • source/sass - каталог для стилей. Каждый scss-файл из этого каталога (не из подкаталогов) будет собран в единый css-бандл build/css/*.min.css со всем связанными импортами (хранимыми в подкаталогах).
    • source/sass/base - каталог для общих стилей.
    • source/sass/blocks - каталог для БЭМ-блоков.
  • source/sprite - каталог для иконок, которые собираются в build/img/sprite.svg.
  • source/twig - каталог для шаблонов разметки.
    • source/twig/pages - каталог для страниц. Из каждого twig-файла (с учетом подкаталогов) будет создан html-файл.
    • source/twig/layout.twig - общая часть каждой страницы.
• static/ - каталог для изменяемых файлов. В режиме разработки сервер видит их, в режиме сборки они копируются в build/ с сохранением структуры подпапок, например:
  • static/fonts/ - каталог для шрифтов.
  • static/img/ - каталог для изображений, по той или иной причине предварительно оптимизированных вручную.
  • static/*.{ico,png,svg,webmanifest} - рекомендуемая область хранения фавиконок (в режиме разработки будут видны в корне сайта, в режиме сборки будут положены в корень папки build/).

Файлы .gitkeep используются для того, чтобы каталоги не были абсолютно пустыми: такие каталоги гит игнорирует. Как только каталог заполнен, файл .gitkeep можно удалить.