Gulp Template

by @id_andyyy
Для тех, кто ценит время. Меньше рутины, больше творчества.

Ключевые возможности шаблона

  • Встроенный шаблонизатор
  • Компиляция SCSS
  • Оптимизация картинок
  • Конвертация и подключение шрифтов
  • Готовые компоненты
  • Стили на все случаи жизни
  • и ещё куча всего

Начало работы

Если вы хотите ознакомиться с документацией самой библиотеки, посетите официальный сайт. В сборке используется Gulp версии 4.0.2.
Скачайте репозиторий и откройте в любом редакторе кода. Выполните команду npm install для установки всех зависимостей.
Для запуска в режиме разработки выполните команду gulp. Код соберётся в папку build.
Для сборки версии для продакшена выполните команду gulp docs. Код соберётся в папку docs.

Структура проекта

Проект состоит из нескольких частей. В папке gulp описаны таски для работы Gulp. Файлы dev.js и fonts-dev.js отвечают за таски в режиме разработки, а docs.js и fonts-docs.js — таски в режиме продакшена. Все таски запускаются из файла gulpfile.js в корне проекта. В файле webpack.config.js описаны настройки для плагина webpack-stream
Папка src предназначена для разработки. Она состоит из следующих подпапок:
  • fonts — для хранения шрифтов, подключаемых без участия Google Fonts.
  • html — для HTML файлов. index.html главный файл, в него подключаются файлы из подпапки blocks.
  • img — для хранения картинок. В папку svgicons помещаются SVG файлы. В папке favicons хранятся favicon.svg и apple-touch-icon.png (для устройств Apple). Для остальных картинок создаются отдельные папки.
  • js — для JavaScript файлов. В подпапке modules хранятся модули, которые потом вручную импортируются в файл index.js.
  • scss — для SCSS файлов. В подпапке base хранятся общие файлы (имеют низший приоритет), в blocks стили блоков (имеют высший приоритет). В файле main.scss никакие стили не прописываются.
  • files — для хранения прочих файлов — аудио, видео и т. д. (необязательная папка).
Подробнее о каждой папке можно почитать перейдя по ссылкам в описании либо в разделе Автоматизация.

Автоматизация

Заранее установленные и настроенные плагины упрощают 90% всех задач разработчика. Ниже подробно рассказно про автоматизированные процессы.

Шаблонизатор

Плагин gulp-file-include собирает HTML файл index.html из файлов блоков. Для подключения такого блока необходимо создать новый HTML файл в папке ./html/blocks/ и подключить его с помощью конструкции:
@@include("./blocks/имя-файла.html")
В папке blocks можно создавать подпапки для более сложных проектов.
Ещё одной удобной конструкцией являются циклы. Для создания цикла необходим JSON файл (его можно разместить в папке ./src/html/data) с массивом из описаний всех объектов и HTML файл (его можно разместить в папке ./src/html/templates) с разметкой одного объекта. В этом файле в те места, куда должны вставляться данные из JSON файла, необходимо разместить конструкции вида @@title. Тогда на это место будут вставляться поля title каждого объекта, описанного в JSON файле. Для подключения этих файлов друг к другу используется синтаксис:
@@loop("./../templates/accordion.html", "./../data/accordion.json")
Пример можно посмотреть в разделе Компоненты. Например, по такому принципу устроен компонент аккордион.
Более подробно ознакомиться с синтаксисом можно на сайте с документацией.

Автоисправление путей

Плагин gulp-replace позволяет пользоваться подсказками редактора во время подключения файлов. То есть все пути к файлам можно прописывать исходя из структуры папки src.

Типограф

Плагин gulp-typograf обеспечивает хорошую читаемость текста на сайте. Он добавляет символы неразрывного пробела между короткими словами. Благодаря этому короткие слова не переносятся на новую строку без более длинных слов, что улучшает связность и читаемость текста. Работает для русского и английского языков. Ещё он заменяет прочие символы на их коды для безопасности и построения семантически-правильного кода. Например, текст на странице:
«Вы мыш?» — спросили коты, обступив мистера Мыша.
«Я болбше не буду», — ответил Мыш.
«А болбше и не надо», — парировали коты.
Код после обработки выглядит следующим образом:
<div class="para example">
  &#171;Вы&#160;мыш?&#187;&#160;&#8212; спросили коты, обступив мистера Мыша.
  &#171;Я&#160;болбше не&#160;буду&#187;,&#160;&#8212; ответил Мыш.
  &#171;А&#160;болбше и&#160;не&#160;надо&#187;,&#160;&#8212;парировали коты.
</div>
Если нужно, чтобы часть текста не была обработана, необходимо заключить её в тег <no-typography></no-typography>.

Компиляция SCSS

Плагин gulp-sass обеспечивает перевод SCSS кода в CSS код. Плагин gulp-sass-glob позволяет подключать SCSS файлы друг в друга. В папке ./src/scss содержатся все файлы стилей. В файл main.scss подключаются остальные файлы. Названия подключаемых файлов должны начинаться с символа _, например, _base.scss. В самом файле main.scss стили не прописываются.
В папке ./src/scss/base находятся файлы с описанием общих стилей:
  • _base.scss — стили для элементов, которые используются во всём проекте.
  • _containers.scss — стили для контейнеров.
  • _fonts-autogen.scss — файл генерируется автоматически при каждой сборке. Содержит стили для подключения шрифтов.
  • _icons.scss — стили для SVG иконок (цвет и размер).
  • _mixins.scss — миксины и функции для адаптивности и картинок.
  • _nullstyle.scss — обнуляющий стиль.
  • _utils.scss — стили для классов, которые влияют на поведение элементов на странице.
  • _vars.scss — переменные, которые используются в проекте (палитра цветов, шрифты, размеры экранов).
В папке ./src/scss/blocks находятся файлы с описанием стилей для блоков. Например, если у нас есть HTML блок about.html, то стили для этого блока будут описаны в файле about.scss.

Автопрефиксер

Плагин gulp-autoprefixer автоматически добавляет вендорные префиксы к CSS-свойствам, чтобы обеспечить кросс-браузерную совместимость. Например, следующие CSS свойства:
.menu-list {
  display: flex;
  column-gap: 22px;
}
После обработки будут выглядеть так:
.menu-list {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-column-gap: 22px;
  -moz-column-gap: 22px;
  column-gap: 22px;
}

Подсказки для стилей

Плагин gulp-sourcemaps используется для создания source maps в процессе сборки проекта. Source maps — это специальный синтаксис, который связывают транспилированный код (например, минифицированный CSS или JavaScript) с его исходным кодом. Это позволяет видеть и работать с оригинальным кодом, даже если в браузере выполняется его обработанная версия. Пример:
Пример работы плагина gulp-sourcemaps
Справа от стилей есть упоминание файла и номера строки, где описываются данные свойства. Например, _text.scss:45.

Работа с SVG

Для добавления иконки в проект, необходимо поместить SVG файл в папку ./src/img/svgicons. Для использования иконки в каком-то месте, необходимо использовать сниппет svgIcon, после чего на место заглушки example написать название необходимого файла.
<svg class="icon icon_example">
  <use href="./img/svgsprite/sprite.symbol.svg#example"></use>
</svg>
Для добавления иконки цвета и размера, необходимо прописать следующие стили (можно использовать SCSS синтаксис) в файле _icons.scss, который находится в папке ./src/scss/base:
.icon_example {
  fill: #6600ff;
  width: 100px;
  height: 50px;
}

Подключение шрифтов

Подключения шрифтов из Google Fonts производится в файле _base.scss папки ./src/scss/base. Рекомендуется использовать плагин Google Fonts в VS Code.
Для подключения шрифтов локально, необходимо поместить файлы шрифтов формата otf или ttf в папку ./src/fonts. Плагины автоматически сконвертируют шрифты в нужный формат и добавит в проект. Кроме того, в папке ./src/scss/base сгенерируется файл _fonts-autogen.scss, в котором все шрифты автоматически подключатся. Никакие стили в этом файле больше писать нельзя, так как он генерируется заново каждый новый билд. Дальшейшее использование шрифтов осуществляется с помощью свойства font-family.

Транспиляция с помощью Babel

Плагин gulp-babel используется для транспиляции JavaScript кода, написанного с использованием современных стандартов ECMAScript (например, ES6, ES7 и выше), в более старую версию JavaScript (например, ES5), которая поддерживается большинством браузеров. Весь написанный разработчиком код автоматически транспилируется и попадает в файл index.js папки build.

Компиляция JS модулей с помощью Webpack

Плагин webpack-stream позволяет интегрировать Webpack. С помощью Webpack происходит минификация JS кода, встроенные оптимизации, обработка импортируемых CSS файлов. В итоге формируется файл index.bundle.js. Настройки плагина описаны в файле webpack.config.js в корне проекта.

Сервер

Плагин gulp-server-livereload используется для запуска локального сервера с функцией автообновления. Он позволяет автоматически обновлять страницу в браузере при изменении файлов в проекте в режиме разработки. Плагин работает автоматически и не требует ручного управления.
Настройки плагина можно изменить в файлах dev.js и docs.js в папке gulp, а именно в тасках server:dev и server:docs соответственно. По умолчанию установлен хост 0.0.0.0 и порт 8000. Это позволяет открывать сайт не только на компьютере разработчика, но и на любом устройстве при вводе в адресной строке ip_адрес_компьютера:порт.

Оптимизация изображений

В режиме продакшена все картинки сжимаются без потери качества. В режими разработки для ускорения сборки проекта, этот шаг пропускается.

Поддержка WebP и Retina

Для корректной работы, каждая картинка должна существовать в двух экземплярах: имя.формат для обычных дисплеев и имя@2x.формат для Retina дисплеев. Если один из файлов будет не найден, картинка отображаться не будет (ошибки вызвано не будет). При этом в атрибуте src тега img подключается картинка без постфикса @2x
Каждая картинка конвертируется в формат WebP для более быстрой загрузки в браузере. При этом HTML код дополняется необходимыми тегами. Например, исходный код выглядит так:
<img src="./../img/image.png" alt="Пример">
Код после обработки будет выглядеть следующим образом:
<picture>
  <source srcset="./img/image.webp 1x, ./img/image@2x.webp 2x" type="image/webp" />
  <source srcset="./img/image.png 1x, ./img/image@2x.png 2x" type="image/png" />
  <img src="./img/image.png" alt="Пример" />
</picture>

Минификация файлов

Файлы HTML и CSS в режими продакшена минифицированы для уменьшения объёма. Из них убраны лишние пробелы и переносы строк. JavaScript файлы минифицируются особым образом с использованием Webpack.

Готовые структуры в SCSS

SCSS файлы в папке ./src/scss/base содержат ряд готовых решений для различных ситуаций.

Готовые классы

Для переиспользования и быстрого использования созданы следующие классы (по желанию их можно удалить или переделать):
  • Класс "main" для элемента main — добавляет отступ сверху для корректного отображения шапки (_base.scss).
  • Класс "list" для элементов ul и ol возвращают маркеры и нумерацию (_base.html).
  • Класс "none" скрывает элемент без следа (_utils.scss).
  • Класс "visually-hidden" скрывает элемент без следа, но оставляет его доступным для поисковых роботов и прочих утилит, способных читать HTML код страницы (_utils.scss).
  • Класс ".no-scroll" скрывает контент, который выходит за границы элемента по вертикали, и предотвращает появление вертикальной полосы прокрутки (_utils.scss).
  • Класс "text-left" центрирует содержимое по левому краю (_utils.scss).
  • Класс "text-right" центрирует содержимое по правому краю (_utils.scss).
  • Класс "text-center" центрирует содержимое по центру краю (_utils.scss).
  • Класс "d-flex" добавляет свойство display: flex (_utils.scss).
  • Класс "flex-center" добавляет свойство justify-content: center (_utils.scss).

Готовые анимации

Для удобства созданы некоторые анимации. Все они находятся в файле _animations.scss в папке ./src/scss/base.
  • Класс "link-animation" добавляет динамичное подчеркивание при наведении на устройствах с мышкой и кратковременное подчеркивание при нажатии на устройствах с сенсорным управлением, примерно вот так.
  • Класс "page-animation" служит основой для анимации появления блоков сайта или всей страницы. Требует дополнительных классов (указаны ниже).
  • Класс "page-animation-right" — блок движется вправо.
  • Класс "page-animation-left" — блок движется влево.
  • Класс "page-animation-up" — блок движется вверх.
  • Класс "page-animation-down" — блок движется вниз.
  • Класс "_is-page-animated" является служебным и появляется в момент завершения анимации.
Работу анимаций обеспечивает файл animations.js в папке ./src/js/modules.

Готовые контейнеры

Для различного размещения контента созданы готовые контейнеры. Свойства описаны в файле _containers.scss в папке ./src/scss/base.
container
container-full
container-left-50
container-right-50
container-right
container-left
container-half-left
container-half-right

Готовые миксины

Некоторые повторяющиеся куски кода были объеденины в миксины. Для использования миксина необходимо использовать конструкцию:
@include mobile {
  width: 10px;
}
Вместо mobile пишется название миксина, в квадратных стилях указываются стили. Список миксинов (все миксины описаны в файле _mixins.scss в папке ./src/scss/base):
  • laptop — стили применяются к устройствам с шириной экрана ноутбука
  • tablet — стили применяются к устройствам с шириной экрана планшета
  • mobile — стили применяются к устройствам с шириной экрана телефона
  • media-bg — изображение будет применено для Retina дисплеев. Пример: background-image: url("./../img/example@2x.jpg").
  • mouse-hover — стили применяются для устройств с устройством ввода мышкой. Если в скобках указать mouse-hover(false), то стили применятся для устройств со способом ввода с помощью касания.

Готовые функции

Функции служат для вычисления значения и подстановки его вместо вызова функции. Функции описаны в файле _mixins.scss в папке ./src/scss/base.
adaptive-value($min-value, $max-value, $min-width, $max-width) — возвращает формулу, которая гарантирует значение $min-value пикселей при размере экрана $min-width пикселей и значение $max-value пикселей при размере экрана $max-width пикселей. Если ширина экрана в данный момент между $min-width и $max-width или вообще вне этого отрезка (например, больше $max-width), то формула обеспечит значение, пропорциональное ширине экрана. Параметры $min-width и $max-width являются необязательными. Если их не указать, то в качестве $min-width будет взята переменная --min-layout-width, а в качестве $max-width переменная --max-layout-width из файла _vars.scss папки ./src/scss/base (подробнее в разделе Переменные). Все параметры должны быть числами без указания единиц измерения. На выходе функция возвращает значение с единицей измерения px.
.element {
  width: adaptive-value(10, 20, 300, 1400); // 10px при ширине 300px и 20px при ширине 1400px
}
percentage-value($dimension, $value, $max-width, $max-height) — возвращает процентное значение от заданного размера $value относительно максимальной ширины $max-width или высоты $max-height, в зависимости от указанного измерения $dimension. Параметр $dimension принимает значения width или height. Параметры $max-width и $max-height являются необязательными. Если их не указать, то в качестве $max-width будет взято значение 1280, а в качестве $max-height значение 832. Все параметры должны быть числами без указания единиц измерения.
.element {
  width: percentage-value(width, 640); // 50% (640 / 1280 * 100%)
  height: percentage-value(height, 416); // 50% (416 / 832 * 100%)
}

Готовые переменные

В файле _vars.scss папки ./src/scss/base хранятся все переменные, которые переиспользуются в других SCSS файлах.
Размеры контейнера:
  • --container-width: 1200px — максимальная ширина контейнера
  • --container-padding: 20px — отступы слева и справа от контейнера
Шрифты:
  • --font-main: "JetBrainsMono", sans-serif — основной шрифт
  • --font-accent: "JetBrainsMono", sans-serif — акцентный шрифт
  • --font-titles: var(--font-accent) — шрифт для заголовков
Цвета:
  • --page-bg: #ffffff — цвет фона страницы
  • --text-main: #000000 — основной цвет текста
  • --main-color: #df494d — основной цвет
  • --light-color: #ffffff — легкий цвет
  • Остальные цвета добавляются в зависимости от проекта
Размеры устройств:
  • --laptop-width: 1439px — максимальный размер ноутбука
  • --tablet-width: 1023px — максимальный размер планшета
  • --mobile-width: 767px — максимальный размер телефона
Размеры макета (только числа, без единиц измерения):
  • --min-layout-width: 360 — минимальная ширина страницы по макету
  • --max-layout-width: 1280 — максимальная ширина страницы по макету
Для изменения цветов тёмной темы используется класс dark.

Готовые компоненты

Для быстрой разработки можно использовать уже готовые компоненты:
Header и бургер-меню — файлы header.html, _header.scss и burger-menu.js. Такой header используется на данной странице.
Аккордион — файлы accordion.html, accordion-section.html, accordion.json, _accordion.scss и accordion.js. Пример:
Lorem, ipsum dolor sit amet consectetur adipisicing elit. Nobis, ipsa!
Lorem ipsum dolor sit amet consectetur adipisicing elit. Ipsum rem nobis molestiae rerum similique numquam, tempora sapiente quam corrupti qui quaerat alias excepturi deleniti quisquam deserunt blanditiis consequatur totam harum debitis placeat tenetur iure quod ex. Autem labore quae sunt. Quae error magni explicabo perferendis doloribus ullam quos possimus reprehenderit?
Lorem ipsum dolor sit, amet consectetur adipisicing elit. Officia aperiam porro consectetur odio aliquid accusantium doloribus maxime nostrum, molestias magni ratione! Voluptas, exercitationem necessitatibus maxime recusandae quae dolore et quis praesentium laudantium asperiores nihil inventore minima deleniti doloremque libero quisquam dolorem ipsa ad fuga aut consectetur saepe dolor quia. Unde aliquid eveniet quibusdam nisi aperiam in suscipit nostrum doloribus soluta. Voluptas eaque fugit quae ratione, libero dolorem aspernatur odit quidem nostrum, molestias suscipit veritatis error. Officia reiciendis sequi nemo quas quod soluta? Sunt beatae magni eligendi, qui facere optio ipsum debitis quisquam ipsam aut doloribus id? Aut assumenda magni unde.
Модальное окно — файлы modal.html, _modal.scss и modal.js. Каждое новое модальное окно должно иметь уникальный id. Пример:
Текущий год — файл current-year.js. Скрипт поддерживает актуальный год: .
Смена темы — файл theme.js. Выбранная тема запоминается даже при обновлении страницы. тему сами.

Сниппеты

Для более быстрой разработки в файле gulp-template.code-snippets в папке .vscode описаны сниппеты.
  • laptop — вызывает подключение миксина laptop
  • tablet — вызывает подключение миксина tablet
  • mobile — вызывает подключение миксина mobile
  • svgIcon — вызывает подключение SVG файла

Ошибки

Часть ошибок отлавливается и показывается в терминале. Нужно следовать инструкциям для их исправления. Предупреждения об обновлении плагинов стоит игнорировать, так как новые версии могут сломать сборку. Не все ошибки могут выводиться в терминал. Самые популярные из них:
  • Не работает шаблонизатор (теги @@include и @@loop). Проверьте правильность написания путей к файлу.
  • Стили не применяются. Проверьте, нет ли противоречий со стилями в других файлах. Стили в папке base имеют низший приоритет, файлы подключаются по порядку, описанному в файле main.scss. Файлы из папки blocks имеют высший приоритет и подключаются по алфавиту.
  • Не работают функции. Проверьте правильность указываемых параметров и способ применения функции.
  • Непонятные проблемы с картинками. Попробуйте пересобрать проект.
  • Не отображается картинка (не SVG файл). Стоит проверить наличие файла с постфиксом @2x, предназначенный для Retina дисплеев.
  • Не отображается иконка (SVG файл). Нужно указать свойство fill или stroke, а также задать размер для класса иконки.
  • Предыдущая проблема сохраняется. Попробуйте закрыть вкладку с сайтом и открыть снова. Можно попробовать другой браузер.
  • После внесения изменений сайт не обновился. Пересоберите проект.
Если проблема не исчезла, проверьте, правильно ли вы разобрались в работе того или иного процесса. Проверьте все пути к файлам, наличие нужных классов, единицы измерения значений. Перечитайте нужный пункт документации ещё раз. Проверьте, не является ли предполагаемая ошибка обычным поведением какого-нибудь плагина. Попробуйте пересобрать проект, открыть страницу с сайтом в другом браузере. Попробуйте удалить папку node_modules и заново выполнить команду npm install. Поищите вашу ошибку в интернете или спросите ChatGPT и его аналоги. Если ошибка всё ещё не исправлена, создайте Issue на Github, если такой проблемы там ещё не поднимали.