Сборка работает на 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.

1. Клонируйте репозиторий:

   git clone [email protected]:htmlacademy/html2-basic-template.git

2. Установите зависимости проекта:

   npm ci

3. Начните работу (должен запуститься браузер):

   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 - проверяет отступы с помощью editorConfig
  • npm run lint:markup - проверяет HTML-разметку через W3C-валидатор
  • npm run lint:html - проверяет разметку по правилам linthtml
  • npm run lint:bem - проверяет правильное использование БЭМ в разметке
  • npm run lint:styles - проверяет проект на совместимость с stylelint
  • npm 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/                 # только при продакшен-сборке
        ├── [email protected]
        ├── [email protected]
        ├── [email protected]
        ├── [email protected]
        └── 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/.