Сборка работает на gulp 4 версии
Для работы с репозиторием на вашем компьютере потребуется 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 # Публикует проект и создаёт ссылку на проект
├── raw/ # Папка для «сырых» файлов (игнорируются гитом)
│ ├── icons/ # Папка для оригиналов svg-иконок
│ └── images/ # Папка для оригиналов картинок
├── source/ # Исходники проекта
│ ├── favicons/ # Папка для фавиконок (кроме favicon.ico)
│ ├── 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:raster
- оптимизирует растровые изображения изraw/images/
вsource/images/
npm run optimize:vector
- оптимизирует векторные изображения изraw/images/
вsource/images/
Все 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
Абсолютно всю растровую графику с двухкратной плотностью из макета складывайте в raw/images/
. Здесь графика игнорируется гитом.
После того как добавите графику сразу запускайте команду npm run optimize:raster
(или просто npm run optimize
) для оптимизации графики и создания .webp
-версии. Команду нужно запускать один раз при появлении новой графики в проекте.
Новая оптимизированная графика с разной плотностью и суффиксами плотности в именах файлов появится в source/images
. Эту, уже оптимизированную графику нужно коммитить.
Векторную графику для спрайта (иконки) складывайте в:
└── raw/
└── icons/
Контентную векторную графику (логотип, графики, иллюстрации) складывайте в:
└── raw/
└── images/
Запуск команды npm run optimize:vector
поместит оптимизированные копии этих svg-файлов в соответствующие папки в исходниках:
└── source/
├── icons/
└── images/
При продакшен-сборке автоматизация перенесёт всю графику из 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
Варианты фавиконок форматов PNG и SVG следует размещать в source/favicons/
.
Файлы favicon.ico
и manifest.webmanifest
— в source/
:
└── source/
├── favicons/
│ ├── 180.png
│ ├── 192.png
│ ├── 512.png
│ └── icon.svg
├── favicon.ico
└── manifest.webmanifest
Все шрифтовые файлы лежат в 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/
.