Сборка работает на 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 [email protected]: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/ # только при продакшен-сборке
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
└── 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/.