Используется Gulp 4
Для работы с данной сборкой в новом проекте, склонируйте все содержимое репозитория
git clone <this repo>
Затем, находясь в корне проекта, запустите команду npm i
, которая установит все находящиеся в package.json зависимости.
После этого вы можете использовать любую из предложенных команд сборки (итоговые файлы попадают в папку app корневой директории):
gulp
- базовая команда, которая запускает сборку для разработки, используя browser-sync
gulp build
- команда для продакшн-сборки проекта. Все ассеты сжаты и оптимизированы для выкладки на хостинг.
gulp cache
- команда, которую стоит запускать после gulp build
, если вам нужно загрузить новые файлы на хостинг без кэширования.
gulp backend
- команда для бэкенд-сборки проекта. Она лишена ненужных вещей из dev-сборки, но не сжата, для удобства бэкендера.
gulp zip
- команда собирает ваш готовый код в zip-архив.
├── gulpfile.babel.js/ # Папка с настройками Gulp
│ ├── config # Настройки Gulp
│ │ └── paths.js # Пути к папкам и файлам
│ ├── tasks # Задачи Gulp
│ │ ├── cache-task.js # Задача для кэширования файлов
│ │ ├── clean.js # Задача для очистки папки сборки
│ │ ├── html-include.js # Задача для сборки HTML
│ │ ├── images.js # Задача для обработки изображений
│ │ ├── index.js # Входной файл задач
│ │ ├── resources.js # Задача для копирования ресурсов
│ │ ├── rewrite.js # Задача для перезаписи ссылок на ассеты
│ │ ├── scripts.js # Задача для обработки JS
│ │ ├── scripts-backend.js # Задача для обработки JS для бэкенда
│ │ ├── styles.js # Задача для обработки CSS
│ │ ├── styles-backend.js # Задача для обработки CSS для бэкенда
│ │ ├── svg-sprites.js # Задача для сборки SVG спрайтов
│ │ └── zip.js # Задача для сборки в zip-архив
│ └── index.js # Главный файл Gulp
├── src/ # Исходники
│ ├── js # Скрипты
│ │ └── main.js # Главный скрипт
│ │ ├── _vars.js # файл с переменными проекта
│ │ ├── _vendor.js # файл с подключениями библиотек
│ │ ├── _components.js # файл с готовыми функциями на js
│ │ ├── _components.js # файл с подключениями компонентов
│ │ ├── components # js-компоненты
│ │ ├── vendor # папка для загрузки локальных версий библиотек
│ ├── scss # Стили сайта (препроцессор sass в scss-синтаксисе)
│ │ └── main.scss # Главный файл стилей
│ │ └── vendor.scss # Файл для подключения стилей библиотек из папки vendor
│ │ └── _fonts.scss # Файл для подключения шрифтов (можно использовать миксин)
│ │ └── _mixins.scss # Файл для подключения миксинов из папки mixins
│ │ └── _vars.scss # Файл для написания css- или scss-переменных
│ │ └── _settings.scss # Файл для написания глобальных стилей
│ │ ├── components # scss-компоненты
│ │ ├── mixins # папка для сохранения готовых scss-компонентов
│ │ ├── vendor # папка для хранения локальных css-стилей библиотек
│ ├── partials # папка для хранения html-частей страницы
│ ├── img # папка для хранения картинок
│ │ ├── svg # специальная папка для преобразования svg в спрайт
│ ├── resources # папка для хранения иных ассетов - php, видео-файлы, favicon и т.д.
│ │ ├── fonts # папка для хранения шрифтов в формате woff2
│ └── index.html # Главный html-файл
└── package.json # файл с настройками сборки и установленными пакетами
└── .editorconfig # файл с настройками форматирования кода
└── .ecrc # файл с настройками пакета editorconfig-checker (исключает ненужные папки)
└── .stylelintrc # файл с настройками stylelint
└── README.md # документация сборки
- npm-скрипты
- Работа с html
- Работа с CSS
- Работа с JavaScript
- Работа со шрифтами
- Работа с изображениями
- Работа с иными ресурсами
- Типограф
- Рекомендуемые плагины VS Code
- Локальные сниппеты
- Готовые модули
- Заключение
Вы можете вызывать gulp-скрипты через npm. Также в сборке есть возможность проверять код на соответствие конфигу (editorconfig) и валидировать html.
npm run html
- запускает валидатор html, запускать нужно при наличии html-файлов в папке app.
npm run code
- запускает editorconfig-checker для проверки соответствия конфиг-файлу.
Благодаря плагину gulp-file-include вы можете разделять html-файл на различные шаблоны, которые должны храниться в папке partials. Удобно делить html-страницу на секции.
Для вставки html-частей в главный файл используйте
@include('partials/filename.html')
Если вы хотите создать многостраничный сайт - копируйте index.html, переименовывайте как вам нужно, и используйте.
При использовании команды gulp build
, вы получите минифицированный html-код в одну строку для всех html-файлов.
В сборке используется препроцессор sass в синтаксисе scss.
Стили, написанные в components, следует подключать в main.scss.
ВАЖНО: Обязательно удалить стили, которые написаны в main.scss для .page__body
.
Чтобы подключить сторонние css-файлы (библиотеки) - положите их в папку vendor и подключите в файле _vendor.scss
Если вы хотите создать свой миксин - делайте это в папке mixins, а затем подключайте в файл _mixins.scss.
Если вы хотите использовать scss-переменные - подключите _vars.scss также в main.scss или в любое другое место, где он нужен, но обязательно удалите :root.
Для подключения css-файлов используйте директиву
@import
В итоговой папке app/css создаются два файла:
main.css - для стилей страницы,
vendor.css - для стилей всех библиотек, использующихся в проекте.
При использовании команды gulp build
, вы получите минифицированный css-код в одну строку для всех css-файлов.
Для сборки JS-кода используется webpack.
JS-код лучше делить на компоненты - небольшие js-файлы, которые содержат свою, изолированную друг от друга реализацию. Такие файлы помещайте в папку components, а потом импортируйте в файл _components.js
В файле vars.js должны храниться базовые переменные проекта, вроде нахождения элементов и т.д.
В файле main.js ничего менять не нужно, он сделан просто как результирующий.
Подключать сторонние библиотеки можно через npm, для этого существует файл _vendor.js. Импортируйте туда подключения.
Если какой-то библиотеки нет в npm или просто нужно подключить что-либо локальным файлом - кладите его в папку vendor и точно так же импортируйте, но уже с путем до файла.
При использовании команды gulp build
, вы получите минифицированный js-код в одну строку для всех js-файлов.
Т.к. автор не поддерживает IE11, в сборке реализована поддержка только формата woff2 (это значит, что в миксине подключения шрифтов используется только данный формат).
Загружайте файлы woff2 в папку resources/fonts, а затем вызывайте миксин @font-face
в файле _fonts.scss.
Также не забудьте прописать эти же шрифты в <link preload>
в html.
Любые изображения, кроме favicon кладите в папку img.
Если вам нужно сделать svg-спрайт, кладите нужные для спрайта svg-файлы в папку img/svg. При этом, такие атрибуты как fill, stroke, style будут автоматически удаляться. Иные svg-файлы просто оставляйте в папке img.
При использовании команды gulp build
, вы получите минифицированные изображения в итоговой папке img.
В сборке доступна поддержка webp и avif форматов. Подключить их вы можете через тег picture
. Для background можно использовать обычные jpg или png, либо использовать image-set
там, где это возможно.
Любые ресурсы (ассеты) проекта, под которые не отведена соответствующая папка, должны храниться в папке resources. Это могут быть видео-файлы, php-файлы (как, например, файл отправки формы), favicon и прочие.
Для корректного отображения текста на странице был подключен плагин типограф, которые автоматически добавит неразрывные пробелы и иные символы, чтобы текст везде отображался по всем правилам русского языка.
Я рекомендую использовать именно VS Code, и в сборке реализовано взаимодействие именно с этим редактором. Так, при открытии папки со сборкой в VS Code, редактор предложит вам ранее не установленные плагины, которые подойдут для корректной работы сборки.
Самый важный из них – projects snippets, этот плагин "включает" локально написанные сниппеты для сборки.
Для удобства и быстроты разработки были добавление локальные сниппеты (находятся в папке .vscode/snippets), которые работают благодаря плагину, описанному выше. Все сниппеты начинаются с префикса g-. В сниппетах пока только html (быстрое создание навигации, соцсетей, корректного тега picture с webp и avif и так далее).
Некоторые сниппеты тесно связаны с scss-миксинами, например кнопка-бургер. Сниппет g-burger создаст вам html-разметку бургера, а подключение миксина @include burger добавит для него стили, что крайне удобно.
Полный список сниппетов с поддержкой миксинов будет опубликован позже.
В сборку постепенно добавляются готовые, часто-используемые модули под различные задачи. Ниже будет перечислен уже добавленный функционал.
Вы можете очень быстро добавить рабочий бургер к себе на страницу, для этого нужно:
- В html вызвать сниппет
g-burger
- На ваше потенциальное меню в html добавить атрибут
data-menu
- В scss вызвать миксин
burger
.burger { @include burger }
- Зайти в файл js/_functions.js и раскомментировать строку с подключением js-файла бургера
- Настроить стили показа меню под себя с помощью класса
menu--active
Необязательно использовать функции именно в файле functions, делайте как удобно вам.
Вы можете очень быстро добавить рабочее модальное окно к себе на страницу, для этого нужно:
- В html вызвать сниппет
g-graph-btn
. Он создаст кнопку для модального окна, ваша задача лишь заполнить атрибутdata-graph-path
- Далее вызвать сниппет
g-graph-modal
. Он создаст базовую разметку окна. Ваша задача - сделать окно по макету, заполнить контент и обязательно обозначить атрибутdata-graph-target
с тем же значением, что и уdata-graph-path
- Зайти в файл vendor.scss и раскомментировать строку с подключением файла graph-modal.min.css
- Зайти в файл js/_functions.js и раскомментировать строку с импортом и подключением библиотеки
GraphModal
Необязательно использовать фунции именно в файле functions, делайте как удобно вам.
Вы можете отключать\включать скролл на странице (работает даже на iPhone). Для этого нужно:
- Зайти в файл js/_functions.js и раскомментировать строку с импортом функций
disableScroll
,enableScroll
. Важно!. Если на странице присутствуют блоки с фиксированным позиционированием (например, шапка), добавьте ей классfix-block
, чтобы этот блок не прыгал при отключении скролла.
Необязательно использовать функции именно в файле functions, делайте как удобно вам.
Вы можете очень быстро добавить рабочие табы к себе на страницу, для этого нужно:
- В html вызвать сниппет
g-tabs
. Он создаст разметку для табов, ваша задача лишь заполнить атрибутdata-tabs
- Для класса
.tabs
вызвать миксинtabs
в scss - Зайти в файл js/_functions.js и раскомментировать строку с импортом и подключением библиотеки
GraphTabs
Необязательно использовать функции именно в файле functions, делайте как удобно вам.
Чтобы сгладить управление частоиспользуемыми событиями, вы можете использовать готовую функцию throttle. Для этого нужно:
- В нужном месте импортировать функцию throttle()
- Написать нужную вам функцию, например, func()
- Создать переменную, в которую поместить вызов вашей фукнции внутри throttle, например:
let f = throttle(func)
- Использовать эту переменную как функцию в вызове, например:
window.addEventListener('resize', f)
Необязательно использовать функции именно в файле functions, делайте как удобно вам.
Нередко блоки с высотой 100vh вызывают проблемы в мобильных браузерах. Решить это поможет готовый модуль fix-fullheight:
- Раскомментируйте строку с импортом файла fix-fullheight.js
- Назначьте на нужный вам блок высоту не 100vh, а
var(--vh)
Для этой функции используется ранее упомянутый throttle. Вы можете убрать его, либо изменить время внутри файла fix-fullheight.js.
Необязательно использовать функции именно в файле functions, делайте как удобно вам.
Все данные функции вы можете вызывать там где вам удобно, необязательно именно в _functions.js. Тут все зависит уже от проекта.
Спасибо всем, кто использует сборку! Если вы заметили какую-либо ошибку, пришлите пожалуйста ишью с подробным описанием проблемы, я все смотрю и постараюсь решить. Спасибо!