Сборка работает на gulp 5 версии
Для работы с репозиторием на вашем компьютере потребуется Git и Node.js. Перед началом работы убедитесь, что все программы работают. Для этого в терминале введите:
-
для Git
git --version
Git примерно ответит
git version 2.42.0.windows.1
версия не важна. Главное, что git отреагировал и написал ответ
-
для Node.js
node -v
Node.js примерно ответит
v18.18.0
важно, чтобы была действующая LTS версия (первое число — чётное), то есть не ниже 20.9 или не ниже 18.18.
-
Клонируйте репозиторий:
git clone git@github.com:htmlacademy/html2-basic-template.git
-
Установите зависимости проекта:
npm ci
-
Начните работу (должен запуститься браузер):
npm start
В каждой папке есть README.md
файл, который имеет более полное описание по работе с папкой
├── .github/ # Специальная папка для github
│ └── workflows/ # Автоматизация для github actions
│ ├── check.yml # Запускает линтеры на Гитхабе
│ └── gh-pages.yml # Публикует проект и создаёт ссылку на проект
├── source/ # Исходники проекта
│ ├── favicons/ # Папка для фавиконок (кроме favicon.ico, его в source переложить вручную)
│ ├── fonts/ # Папка для шрифтов
│ ├── icons/ # Папка для оптимизированных svg-иконок для преобразования их в спрайт (stack)
│ ├── images/ # Папка для оптимизированных картинок
│ ├── scripts/ # Скрипты
│ │ └── index.js # Главный скрипт
│ ├── styles/ # Папка для препроцессорных файлов sass
│ │ ├── blocks/ # Стили БЭМ-блоков
│ │ │ └── header.scss # Стили для конкретного БЭМ-блока
│ │ ├── common/ # Папка для общих стилей (не БЭМ-блоки)
│ │ │ ├── fonts.scss # Подключение шрифтов к проекту
│ │ │ ├── global.scss # Глобальные стили, которые касаются всего проекта
│ │ │ └── variables.scss # Переменные для всего проекта
│ │ └── styles.scss # Основной стилевой файл с импортами всех остальных
│ ├── vendor # Папка для сторонних бибилотек
│ └── index.html # HTML-файл для главной страницы
├── .editorconfig # Настройки форматирования текстовых файлов
├── .eslintrc # Правила для eslint
├── .gitignore # Настройки игнорирования файлов для git
├── .linthtmlrc # Правила для linthtml
├── .stylelintrc # Правила для stylelint
├── gulpfile.js # Автоматизация для Gulp
├── package.json # Зависимости проекта, скрипты, настройки проекта
├── package-lock.json # Зависимости проекта
└── README.md # Документация
npm start
- запускает сборку с сервером для разработки проектаnpm run build
- создаёт папкуbuild
с оптимизированными файлами для продакшена
npm run preview
- позволяет посмотреть результат работы prod-версии сборкиnpm run lint
- запускает все проверки (занимает длительное время):npm run lint:spaces
- проверяет отступы с помощью editorConfignpm run lint:markup
- проверяет HTML-разметку через W3C-валидаторnpm run lint:html
- проверяет разметку по правилам linthtmlnpm run lint:bem
- проверяет правильное использование БЭМ в разметкеnpm run lint:styles
- проверяет проект на совместимость с stylelintnpm run lint:scripts
- проверяет скрипты по правилам eslint
npm run optimize
- запускает все оптимизации изображений:npm run optimize:icons
- вsource/icons/
оптимизирует векторные иконкиnpm run optimize:images
- вsource/images/
оптимизирует векторыне и конвертирует растровые изображения (растровые оригиналы удаляются автоматически)npm run optimize:favicons
- вsource/favicons/
генерирует все необходимые варианты фавиконок, а также webmanifest (векторные оригиналы удаляются автоматически)
Все HTML-файлы с разметкой складывайте в папку source/
.
└── source/
├── index.html
├── catalog.html
└── form.html
Из папки source/
сборка переносит файлы в папку build/
.
└── build/
├── index.html
├── catalog.html
└── form.html
Все стили находятся в папке source/styles/
.
└── source/
└── styles/
├── blocks/
│ └── header.scss
├── common/
│ ├── fonts.scss
│ ├── global.scss
│ └── variables.scss
└── styles.scss
Все БЭМ-блоки и остальные препроцессорные файлы подключайте в source/styles/styles.scss
:
/* COMMON */
@import "./common/variables.scss";
@import "./common/global.scss";
@import "./common/fonts.scss";
/* BLOCKS */
@import "./blocks/header.scss";
БЭМ-блоки импортируйте в секцию /* BLOCKS */
.
Все препроцессорные файлы сборка обработает и превратит в styles.css
. Файл styles.css
сборка перенесёт в:
└── build/
└── styles/
└── styles.css
Во всех трёх ниже описанных случаях коммитить нужно оптимизированную графику.
Из макета всю растровую графику (только с двухкратной плотностью, но без суффикса плотности @2x
в имени) и всю контентную векторную графику (логотип, графики, иллюстрации) складывайте в:
└── source/
└── images/
Здесь растровая графика без суффикса плотности игнорируется гитом.
Запуск команды npm run optimize:images
оптимизирует векторную графику и конвертирует растровую в форматы Webp
и Avif
для двухкратной и однократной плотности пикселей с соответствующими суффиксами.
Векторную графику для спрайта (иконки) складывайте в:
└── source/
└── icons/
Запуск команды npm run optimize:icons
оптимизирует все иконки.
Векторные фавиконки (все, что есть в макете) разместите в:
└── source/
└── favicons/
Имена исходных файлов должны быть такими:
└── source/
└── favicons/
├── 16.svg # Специальная версия размером 16×16. Добавляй её только при её наличии в макете.
├── 32.svg # Основной вариант размером 32×32.
└── touch.svg # Большая тач-иконка без скруглений и прозрачностей.
Запуск команды npm run optimize:favicons
сгенерирует все необходимые фавиконки и вебманифест. Кроме этого сгенерируется файл Links.md
с кодом нужных тегов link
. Заберите этот код в head
разметки (md-файл после этого можно удалить).
Переместите favicon.ico
и manifest.webmanifest
в source/
. Получится так:
└── source/
├── favicons/
│ ├── icon-180.png
│ ├── icon-192.png
│ ├── icon-192.webp
│ ├── icon-512.png
│ ├── icon-512.webp
│ └── icon.svg
├── favicon.ico
└── manifest.webmanifest
По необходимости исправь пути в вебманифесте и тегах link
.
При продакшен-сборке автоматизация перенесёт всю графику из source/images/
в build/images/
, а из иконок в source/icons/
создаст спрайт build/icons/stack.svg
.
НО! При сборке для разработки автоматизация собирает только спрайт в build/icons/
. Папки images/
в build/
не будет совсем — это нормально, дев-сервер знает, что при запросе этих изображений ему надо смотреть в source/images/
. Это также относится к фавиконкам и шрифтам.
└── build/
├── icons/ # при любой сборке
│ └── stack.svg
└── images/ # только при продакшен-сборке
├── hero@1x.png
├── hero@1x.webp
├── hero@2x.png
├── hero@2x.webp
└── logo.svg
Все шрифтовые файлы лежат в source/fonts/
. Сборка переносит их в build/fonts/
.
└── build/
└── fonts/
├── open-sans.woff2
└── open-sans-bold.woff2
Все скрипты лежат в source/scripts/
.
└── source/
└── scripts/
├── index.js
└── modal.js
Сборка переносит их в build/scripts/
.
└── build/
└── scripts/
├── index.js
└── modal.js
Для удобства внесения сторонних библиотек в ваш проект, вы можете использовать папку source/vendor/
. В этой папке вы можете размещать любые файлы, связанные с внешними библиотеками.
Например, предположим, что вы хотите добавить в проект библиотеку, которая включает в себя как стилевой файл library.css
, так и скрипты library.js
. Чтобы интегрировать их в ваш проект, следуйте этим шагам:
Положите файлы библиотеки в папку source/vendor/
, как показано ниже:
└── source/
└── vendor/
├── library.css
└── library.js
Если у вас есть несколько библиотек с разными файлами, вы можете группировать файлы одной библиотеки в ее собственную подпапку. Например:
└── source/
└── vendor/
└── library/
├── library.css
└── library.js
При сборке вашего проекта, все файлы из папки source/vendor/
будут включены в папку build/vendor/
, сохраняя их структуру. Например:
└── build/
└── vendor/
└── library/
├── library.css
└── library.js
Таким образом, вы можете удобно организовать и внедрить сторонние библиотеки в ваш проект, сохраняя их структуру в папке source/vendor/
.