Автоматизированная сборка HTML-проекта.

• Основные возможности
• Подготовка к работе
• Инициализация и запуск
• Структура проекта
• Настройки
• • Список основных параметров
• • Запуск с параметрами командной строки
• • Пресеты и комбинирование параметров
• Работа с файлами
• • HTML-файлы
• • SASS-файлы
• • JS-файлы
• • Инициализация Swiper
• • Изображения
• • Конвертация SVG в Base64
• • Иконки Icomoon
• • Шаблоны (Handlebars, Mustache)
• • Подключение библиотек и плагинов
• Загрузка файлов на сервер
• Создание ZIP-архивов
• Аудит страниц (Lighthouse)

• Компиляция SASS / SCSS файлов в CSS, автопрефиксы, группировка медиа-запросов.
• Компиляция JS файлов в стандарт ES5 с использованием Babel (опционально).
• Компиляция Pug файлов c поддержкой импорта данных из JSON файлов.
• Импорт HTML / JSON файлов, итерация JSON массивов и доступ к настройкам сборки в HTML / JS файлах.
• Оптимизация и сжатие растровых (JPG, PNG, GIF) и векторных (SVG) изображений.
• Конвертация SVG-файлов в Base64 и последующий импорт в CSS.
• Конвертация изображений в формат WebP (опционально).
• Автоматический импорт иконок Icomoon в SASS / SCSS из файла selection.json.
• Слежение за файлами (watch) и автоматическая перекомпиляция файлов.
• Компиляция страницы со списком HTML файлов проекта и перечня используемых библиотек и компонентов (опционально).
• Линтинг SASS и JS файлов с помощью Stylelint и ESLint.
• Генерация карт кода (sourcemaps) (опционально).
• Создание ZIP-архивов с исходными и скомпилированными файлами (опционально).
• Загрузка файлов на сервер по FTP (опционально).
• Генерация отчетов Lighthouse на локальном сервере.
• Режим отладки.

Для запуска проекта необходимо наличие установленного в системе Node.js. Если необходимо, установите его с официального сайта.

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

gulp -v

Для установки Gulp воспользуйтесь командой:

npm i --global gulp-cli

Если ранее вы уже устанавливали Gulp глобально, удалите его (подробнее) и установите пакет gulp-cli:

npm rm --global gulp
npm i --global gulp-cli

# Перейдите в папку с проектом
cd /path/to/project/

# Установите необходимые зависимости
npm i

# Запустите сборку
gulp

gulp-project                        # Корневая директория
├── gulp                            # Файлы Gulp
│   ├── helpers                     # Вспомогательные функции
│   ├── tasks                       # Задачи
│   │   ├── bootstrap.js            # Сборка Bootstrap
│   │   ├── browser.js              # Запуск браузера после загрузки файлов на сервер
│   │   ├── build.js                # Запуск сборки
│   │   ├── clean.js                # Очистка временных файлов директорий
│   │   ├── clear-cache.js          # Очистка кэша
│   │   ├── common.js               # Формирование списка страниц проекта
│   │   ├── compress.js             # Конкатенация и минификация файлов
│   │   ├── default.js              # Задача по умолчанию
│   │   ├── deploy.js               # Загрузка файлов на сервер и открытие браузера
│   │   ├── dev.js                  # Запуск сборки в dev режиме
│   │   ├── html.js                 # Компиляция HTML файлов
│   │   ├── icomoon.js              # Импорт иконок Icomoon
│   │   ├── images.js               # Пакетное сжатие и преобразование изображений
│   │   ├── js.js                   # Компиляция JS-файлов
│   │   ├── reload.js               # Перезагрузка браузера
│   │   ├── sass.js                 # Компиляция SASS/SCSS файлов в CSS
│   │   ├── steady.js               # Копирование статических файлов
│   │   ├── upload.js               # Запуск FTP-соединения и передача файлов на сервер
│   │   ├── steady.js               # Копирование статических файлов
│   │   ├── vendor.js               # Копирование файлов библиотек и плагинов
│   │   ├── watch.js                # Слежение за изменениями файлов
│   │   ├── webserver.js            # Запуск Browsersync
│   │   └── zip.js                  # Создание zip-архивов с исходными и выходными файлами
│   ├── config.js                   # Глобальные настройки проекта
│   └── defaults.js                 # Пресеты и значения командных параметров по умолчанию
├── src                             # Исходные файлы
│   ├── common                      # Список страниц проекта
│   ├── data                        # JSON-файлы для хранения данных
│   ├── fonts                       # Шрифты
│   ├── icomoon                     # Исходные файлы Icomoon
│   ├── includes                    # Включаемые файлы HTML
│   ├── images                      # Изображения
│   ├── javascripts                 # Файлы JavaScript
│   │   ├── base                    # Глобальные файлы (по умолчанию компилируются в один файл)
│   │   ├── components              # Компоненты (по умолчанию компилируются в отдельные файлы)
│   │   ├── partials                # Вспомогательные функции
│   │   ├── import                  # Импорт модулей для Browserify / Babel
│   │   └── polyfills               # Полифиллы для браузеров
│   ├── pug                         # Файлы Pug
│   │   ├── includes                # Включаемые файлы
│   │   ├── layouts                 # Шаблоны страниц и компонентов
│   │   └── partials                # Миксины и вспомогательные функции
│   ├── styles                      # Файлы SASS
│   │   ├── base                    # Глобальные файлы (по умолчанию компилируются в один файл)
│   │   ├── components              # Компоненты (по умолчанию компилируются в отдельные файлы)
│   │   ├── icons                   # Иконки
│   │   ├── partials                # Миксины и вспомогательные функции
│   │   ├── vendor                  # Исходные файлы библиотек и плагинов
│   │   ├── _config.scss            # Глобальные настройки
│   │   ├── _icons.scss             # Иконки
│   │   └── _partials.scss          # Импорт вспомогательных файлов
│   ├── swiper                      # JSON-файлы с параметрами Swiper
│   ├── templates                   # Папка для шаблонов (Handlebars, Mustache и пр.)
│   ├── vectors                     # SVG-файлы для встраивания в CSS
│   ├── vendor                      # Библиотеки и плагины
│   │   ├── css                     # Файлы CSS
│   │   └── js                      # Файлы JavaScript
│   └── home.html                   # Главная страница
├── .browserslistrc                 # Список поддерживаемых браузеров
├── .editorconfig                   # Настройки IDE
├── .env                            # Переменные окружения
├── .eslintrc                       # Настройки ESLint
├── .gitignore                      # Игнорируемые файлы в git
├── .stylelintignore                # Игнорируемые файлы Stylelint
├── .stylelintrc                    # Настройки Stylelint
├── CHANGELOD.md                    # История версий
├── config.js                       # Пользовательские настройки
├── gulpfile.js                     # Основной файл Gulp
├── package-lock.json               # Требуется для запуска команды `npm ci`
├── package.json                    # Файл package.json
└── README.md                       # Документация

Список настроек проекта в порядке убывания приоритета:

• Параметры командной строки (задаются пользователем).
• Пользовательские настройки и пресеты: /config.js.
• Глобальные настройки: /gulp/config.js.
• Настройки командной строки по умолчанию /gulp/defaults.js.

Параметры можно передать с помощью командной строки:

gulp --[param1] value1 --[param2] value2

Для параметров с типом Object значения передаются через символ запятой , одной строкой: (пример: --minify css,js).

gulp --merge css,js

Пример запуска с параметрами:

gulp --babel --minify js --open catalog

В этом случае сборка будет запущена со следующими параметрами:

config = {
    babel: true,
    minify: {
        css: false, // наследуется из параметров по умолчанию
        js: true
    },
    open: `catalog`
}

Если вы хотите переопределить стандартное значение параметров без использования командной строки, вы можете создать пресеты в файле конфигурации /config.js путем добавления в него объекта presets, содержащего нужные параметры.

Пресеты, используемые по умолчанию, доступны в файле /gulp/defaults.js.

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

config.presets = {
    global: {
        index: true,
        open: `home`
    }
}

Параметры из пользовательского пресета применяются, если:

• Название пресета соответствует названию текущей задачи (build для дефолтной задачи, compress, lighthouse и т.д);
• Название пресета передано как параметр командной строки --preset.

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

config.presets = {
    deploy: {
        babel: true,
        compress: true,
        mode: `build`
    }
}

Данный пресет эквивалентен запуску сборки с параметрами:

gulp deploy --babel --compress --mode build

Пример пользовательского пресета, запускаемого из командной строки:

config.presets = {
    myPreset: {
        debug: true,
        minify: {
            css: true,
            js: true
        }
    }
}

Этот пресет будет запущен при явном указании параметра preset:

gulp --preset myPreset

Для удобной работы с HTML и JS-файлами вы можете использовать операторы gulp-file-include:

• @@​include
• @@​if
• @@​for
• @@​loop

Документация и примеры использования можно найти здесь.

HTML-файлы размещены в директории с исходными файлами /src.

Для более удобной организации файлов в директории /src/includes/ созданы вложенные папки. Структура папок является условной и может быть изменена вами на свое усмотрение.

Глобальный файл настроек SASS находится в папке /src/styles/_config.scss.

Вы можете создавать собственные переменные, миксины и функции и размещать их в файле /src/styles/partials/_custom.css, после этого они будут доступны глобально.

• Все файлы из директории /src/styles/base компилируются в один CSS файл, название которого задается в параметре config.files.css.
• Все файлы из директории /src/styles/components компилируются в отдельные CSS файлы с сохранением названия.

Для изменения поведения по умолчанию используйте параметр config.merge.css.

• Все файлы из директории /src/javascripts/base компилируются в один файл, название которого задается в глобальных параметрах config.files.js.
• Все файлы из директории /src/javascripts/components компилируются в отдельные JS файлы с сохранением названия.

Для изменения поведения по умолчанию используйте параметр config.merge.js.

Каждый экземпляр Swiper инициализируется с уникальным ID и сохраняется в глобальный JS-объект window.swipers.

1. В директории /src/data создайте JSON-массив с данными для слайдов (например, slider.json). Название файла должно соответствовать ID свайпера.

Пример файла slider.json:

[
    {
        "id": 1,
        "title": "One",
        "text": "I am first slide"
    }, {
        "id": 2,
        "title": "Two",
        "text": "I am second slide"
    }, {
        "id": 3,
        "title": "Three",
        "text": "I am third slide"
    }
]

2. В директории /src/includes/items создайте HTML-файл с разметкой для отдельного слайда (slide.html).

Пример файла slide.html:

<div class="slide slide--@@id">
    <div class="slide__title">@@title</div>
    <div class="slide__text">@@text</div>
</div>

3. В директории /src/swiper создайте JSON файл, содержащий параметры для свайпера. Название файла должно соответствовать ID свайпера.

Пример файла slider.json:

{
    "slidesPerView": 1,
    "spaceBetween": 15,
    "loop": true,
    "breakpoints": {
        "768": {
            "slidesPerView": 2
        },
        "1200": {
            "slidesPerView": 4,
            "spaceBetween": 25
        }
    }
}

4. В нужном файле импортируйте файл swiper.html, передав ему ID свайпера и название шаблона слайда:

@@include('components/swiper.html', {
    "id": "slider",
    "template": "slide"
})

После инициализации вы можете получить экземпляр Swiper через глобальный объект window.swipers['slider'].swiper.

Переместите изображения в директорию /src/images. Настройки компрессии задаются в параметре config.plugins.imagemin. Для конвертации всех изображений в формат WebP установите параметр config.webp в значение true.

Для конвертации SVG файлов в Base64 и встраивания в CSS переместите их в директорию /src/vectors.

Для добавления иконок в проект распакуйте содержимое ZIP-архива с сайта icomoon.io в директорию /src/icomoon. После этого автоматически сгенерируются CSS-классы иконок и вы сможете использовать их.

Массив из CSS-классов иконок сохраняется в глобальную переменную @@​icons, которая доступна в HTML.

Если вы используете JS-компиляторы для HTML (Handlebars, Mustache и т.п), для хранения шаблонов предусмотрена директория /src/templates.

Все файлы из неё копируются без изменения в папку с выходными файлами.

Если нужной библиотеки нет в репозитории npm или вам по какой то причине не нужно добавлять её в список зависимостей, вы можете добавить файлы вручную в директорию /src/vendor. SASS файлы для библиотек размещаются в директории /src/styles/vendor.

Для импорта сторонних библиотек сначала установите их как зависимости через стандартную команду:

npm i package-name

После этого в параметре config.paths.vendor укажите абсолютный путь до нужных файлов из директории /node_modules (по аналогии с файлом /gulp/config.js).

⚠️ Обратите внимание

При включенном параметре config.babel все библиотеки, импортируемые через параметр config.paths.vendor, игнорируются. Чтобы подключить их, добавьте соответствующие импорты в файле src/javascripts/import/modules.js.

Перед загрузкой файлов на сервер необходимо задать параметры FTP в .env файле.

После этого запустите команду:

gulp deploy

Добавление FTP-хоста

По умолчанию загрузка файлов происходит на хост default. Если необходимо создать еще один хост, добавьте параметры в .env файл:

FTP_CUSTOM_HOST=HOSTNAME
FTP_CUSTOM_USER=USER
FTP_CUSTOM_PASSWORD=PASSWORD
FTP_CUSTOM_DEST=DEST
FTP_CUSTOM_URI=URL

После этого импортируйте параметры в файл config.ftp, в качестве ключа задайте название хоста:

config: {
    ftp: {
        custom: {
            host: process.env.FTP_CUSTOM_HOST,
            user: process.env.FTP_CUSTOM_USER,
            password: process.env.FTP_CUSTOM_PASSWORD,
            dest: process.env.FTP_CUSTOM_DEST,
            uri: process.env.FTP_CUSTOM_URI
        }
    }
}

Для загрузки файлов на хост custom запустите команду:

gulp deploy --host custom

Выборочная загрузка

Если со времени последней загрузки изменялись только основные файлы проекта (HTML, CSS и JS), вы можете загрузить только их, минуя загрузку статических файлов (шрифты, изображения и т.п.) с помощью команды:

gulp deploy --main

Типы основных файлов определяются в параметре config.paths.deploy.main.

Production mode

По умолчанию перед загрузкой файлов включена компрессия файлов и компиляция в ES5, поэтому передавать параметры --compress и --babel не нужно.

Если вы хотите изменить это поведение, отредактируйте пресет config.presets.deploy.

Для создания ZIP-архивов установите параметр config.zip в значение true. Названия файлов задаются в глобальных параметре config.files.zip.

gulp --zip

Google Lighthouse – это инструмент аудита с открытым исходным кодом, который помогает разработчикам повысить производительность и доступность своих веб-проектов.

Отчеты Google Lighthouse генерируются на локальном сервере для каждой страницы проекта после запуска команды:

gulp lighthouse

В зависимости от количества HTML страниц в проекте, выполнение задачи может занять продолжительное время.

The MIT License (MIT)