Merge pull request #46 from firefoxic/feature/work-images

Feature/work-images

Author: nikolai-shabalin

.gitignore

@@ -3,5 +3,5 @@ node_modules
 build
 .idea
 .DS_Store
-source/.raw/**/*.png
-source/.raw/**/*.jpg
+source/.raw/
+!source/.raw/**/README.md

README.md

@@ -1,108 +1,138 @@
-# Сборка для HTML-курсов в HTML Academy
-Сборка работает на gulp 4 версии
+# Сборка для HTML-курсов в HTML Academy
+
+Сборка работает на gulp 4 версии
 
 ## Начало
-Для работы с репозиторием на вашем компьютере потребуется Git и Node.js (18.x.x). Перед началом работы убедитесь, что все программы работают. Для этого в терминале введите:
-- для git
-```bash
-git --version
-```
-git примерно ответит
-```bash
-git version 2.42.0.windows.1
-```
 
-![проверка версии git](assets/git.png)
+Для работы с репозиторием на вашем компьютере потребуется _Git_ и _Node.js_. Перед началом работы убедитесь, что все программы работают. Для этого в терминале введите:
 
-версия не важна. Главное, что git отреагировал и написал ответ
+- для _Git_
 
-- для node.js
-```bash
-node -v
-```
-node.js примерно ответит
-```bash
-v18.18.0
-```
+  ```shell
+  git --version
+  ```
+
+  _Git_ примерно ответит
+
+  ```shell
+  git version 2.42.0.windows.1
+  ```
+
+  ![проверка версии git](assets/git.png)
+
+  версия не важна. Главное, что git отреагировал и написал ответ
+
+- для _Node.js_
+
+  ```shell
+  node -v
+  ```
+
+  _Node.js_ примерно ответит
+
+  ```shell
+  v18.18.0
+  ```
+
+  ![проверка версии node.js](assets/node.png)
+
+  важно, чтобы была действующая LTS версия (первое число — чётное), то есть не ниже 20.9 или не ниже 18.18.
+
+## Установка
+
+1. Клонируйте репозиторий:
+
+    ```shell
+    git clone git@github.com:htmlacademy/html2-basic-template.git
+    ```
+
+2. Установите зависимости проекта:
 
-![проверка версии node.js](assets/node.png)
+    ```shell
+    npm ci
+    ```
 
-важно, чтобы версия была 18.x.x.
+3. Начните работу (должен запуститься браузер):
 
-# Установка
-1. Клонируйте репозиторий `git clone git@github.com:htmlacademy/html2-basic-template.git`
-2. Установите зависимости проекта `npm ci`
-3. Начните работу `npm start` // должен запуститься браузер
+    ```shell
+    npm start
+    ```
 
 ## Структура папок
-В каждой папке есть Readme.md файл, который имеет более полное описание по работе с папкой
 
-```
-├── .github/                      # Специальная папка для github
-│   └── workflows/                # Автоматизация для github actions
-│       ├── check.yml             # Запускает линтеры на Гитхабе
-│       └──  gh-pages.yml         # Публикует проект и создаёт ссылку на проект
+В каждой папке есть `README.md` файл, который имеет более полное описание по работе с папкой
+
+```shell
+├── .github/                      # Специальная папка для github
+│   └── workflows/                # Автоматизация для github actions
+│       ├── check.yml             # Запускает линтеры на Гитхабе
+│       └──  gh-pages.yml         # Публикует проект и создаёт ссылку на проект
 ├── source/                       # Исходники проекта
-│   ├── fonts/                    # Папка для шрифтов
-│   ├── images/                   # Папка для хранения картинок
-│   │   └── icons/                # Специальная папка для преобразования svg в спрайт(stack)
+│   ├── fonts/                    # Папка для шрифтов
+│   ├── images/                   # Папка для хранения картинок
+│   │   └── icons/                # Специальная папка для преобразования svg в спрайт(stack)
 │   ├── js                        # Скрипты
 │   │   └── script.js             # Главный скрипт
-│   ├── sass/                # Папка для препроцессорных файлов sass
+│   ├── sass/                     # Папка для препроцессорных файлов sass
 │   │   └── blocks/               # Стили БЭМ-блоков
-│   │       └── header.scss       # Стили для конкретного БЭМ-блока
-│   │   └── global                # Файл для подключения стилей библиотек из папки
-│   │       ├── fonts.scss        # Подключение шрифтов к проекту
+│   │       └── header.scss       # Стили для конкретного БЭМ-блока
+│   │   └── global                # Файл для подключения стилей библиотек из папки
+│   │       ├── fonts.scss        # Подключение шрифтов к проекту
 │   │       ├── global.scss       # Глобальные стили, которые касаются всего проекта
-│   │       └── variables.scss    # Переменные для всего проекта
-│   ├── vendor                    # Папка для сторонних бибилотек
-│   └──  index.html               # HTML-файл для главной страницы
+│   │       └── variables.scss    # Переменные для всего проекта
+│   ├── vendor                    # Папка для сторонних бибилотек
+│   └──  index.html               # HTML-файл для главной страницы
 └── .editorconfig                 # Настройки форматирования текстовых файлов
-└── .gitignore                    # Настройки игнорирования файлов для git
-└── .stylelintrc                  # Правила для stylelint
-└── gulpfile.js                   # Автоматизация для Gulp
+└── .gitignore                    # Настройки игнорирования файлов для git
+└── .stylelintrc                  # Правила для stylelint
+└── gulpfile.js                   # Автоматизация для Gulp
 └── package.json                  # Зависимости проекта, скрипты, настройки проекта
 └── package-lock.json             # Зависимости проекта
 └── README.md                     # Документация
 ```
 
 ## Основные команды
-- `npm start` - запускает сборку с сервером для разработки проекта
-- `npm run build` - создаёт папку `build` с оптимизированными файлами для продакшена
+
+- `npm start` - запускает сборку с сервером для разработки проекта
+- `npm run build` - создаёт папку `build` с оптимизированными файлами для продакшена
 
 ## Дополнительные команды
-- `npm run optimizeImages` - создаёт оптимизированные изображения в `source/images/`
-- `npm run preview` - посмотреть результат работы prod-версии сборки
-- `npm run lint` - запустить все проверки. Занимает длительное время
-- `npm run lint:bem` - проверить правильно использования БЭМ
-- `npm run lint:markup` - проверить HTML-разметку через W3C-валидатор
-- `npm run lint:styles` - проверить проект на совместимость с stylelint
-- `npm run lint:spaces` - проверить отступы с помощью editorConfig
-- `npm run lint:html` - проверить разметку по правилам linthtml
-
-## Работа с разметкой
-Все HTML-файлы с разметкой складывайте в папку `source/`.
-
-```bash
+
+- `npm run optimizeImages` - создаёт оптимизированные изображения в `source/images/`
+- `npm run preview` - позволяет посмотреть результат работы prod-версии сборки
+- `npm run lint` - запускает все проверки (занимает длительное время)
+- `npm run lint:bem` - проверяет правильное использование БЭМ в разметке
+- `npm run lint:markup` - проверяет HTML-разметку через W3C-валидатор
+- `npm run lint:styles` - проверяет проект на совместимость с stylelint
+- `npm run lint:spaces` - проверяет отступы с помощью editorConfig
+- `npm run lint:html` - проверяет разметку по правилам linthtml
+- `npm run lint:js` - проверяет скрипты по правилам eslint
+
+## Работа с разметкой
+
+Все HTML-файлы с разметкой складывайте в папку `source/`.
+
+```shell
 ├── source/
 │   ├──  index.html
 │   ├──  catalog.html
 │   └──  form.html
 ```
 
-из папки `source/` сборка переносит файлы в папку `build/`.
+Из папки `source/` сборка переносит файлы в папку `build/`.
 
-```bash
+```shell
 ├── build/
 │   ├──  index.html
 │   ├──  catalog.html
 │   └──  form.html
 ```
 
-## Работа со стилями
-Все стили находятся в папке `source/sass/`.
+## Работа со стилями
 
-```bash
+Все стили находятся в папке `source/sass/`.
+
+```shell
 ├── source/
 │   ├── sass
 │   │   └── blocks/
@@ -113,9 +143,8 @@ v18.18.0
 │   │       └── variables.scss
 ```
 
-Все БЭМ-блоки и остальные препроцессорные файлы подключайте в `source/sass/styles.scss`.
+Все БЭМ-блоки и остальные препроцессорные файлы подключайте в `source/sass/styles.scss`.
 
-_styles.scss_
 ```scss
 /* GLOBAL */
 @import "global/variables";
@@ -126,48 +155,52 @@ _styles.scss_
 @import "blocks/header";
 ```
 
-БЭМ-блоки импортируйте в секцию `/* BLOCKS */`.
+БЭМ-блоки импортируйте в секцию `/* BLOCKS */`.
 
 Все препроцессорные файлы сборка обработает и превратит в `styles.css`. Файл `styles.css` сборка перенесёт в
 
-```bash
+```shell
 ├── build/
 │   └──  css/
 │        └──  styles.css
 ```
 
-## Работа с графикой
-Абсолютно всю графику складывайте в `source/.raw`.
-После того как добавите графику сразу запускайте команду `npm run optimizeImages` для оптимизации графики и создания `.webp`-версии. Команду нужно запускать один раз при появлении новой графики в проекте.
-Новая оптимизированная графика появится в `source/images`.
+## Работа с графикой
+
+Абсолютно всю растровую графику с двухкратной плотностью из макета складывайте в `source/.raw`. Здесь графика игнорируется гитом.
 
-Векторную графику для спрайта складывайте в `source/images/icons/`. Автоматизация создаст из иконок файл `stack.svg`.
+После того как добавите графику сразу запускайте команду `npm run optimizeImages` для оптимизации графики и создания `.webp`-версии. Команду нужно запускать один раз при появлении новой графики в проекте.
 
-```bash
+Новая оптимизированная графика разной плотностью и суффиксами плотности в именах файлов появится в `source/images`. Эту, уже оптимизированную графику нужно коммитить.
+
+Векторную графику для спрайта складывайте в `source/images/icons/`. Автоматизация создаст из иконок файл `stack.svg`.
+
+```shell
 ├── source/
 │   ├── .raw/
 │   ├── images/
 │   │   └── icons/
 ```
 
-Всю графику автоматизация перенесёт в `build/images/`.
+Всю графику автоматизация перенесёт в `build/images/`.
 
-```bash
+```shell
 ├── build/
 │   └──  images/
-│        └── icons       # папка для спрайта
-│            └── stack.svg # спрайт
+│        └── icons                # папка для спрайта
+│            └── stack.svg        # спрайт
 │        ├── bg.jpg
 │        ├── bg.webp
 │        ├── hero.png
 │        ├── hero.webp
 │        └── burger.svg
 ```
 
-## Работа со шрифтами
-Все шрифтовые файлы лежат в `source/fonts/`. Сборка переносит их в `build/fonts/`.
+## Работа со шрифтами
+
+Все шрифтовые файлы лежат в `source/fonts/`. Сборка переносит их в `build/fonts/`.
 
-```bash
+```shell
 ├── build/
 │   └──  fonts/
 │        ├──  open-sans.woff2
@@ -176,54 +209,60 @@ _styles.scss_
 │        └──  open-sans-bold.woff
 
 ```
-## Работа со скриптами
-Все скрипты лежат в `source/script/`.
 
-```bash
+## Работа со скриптами
+
+Все скрипты лежат в `source/script/`.
+
+```shell
 ├── source/
 │   ├── js
 │   │   ├── script.js
 │   │   └── modal.js
 ```
 
-Сборка переносит их в `build/script/`.
-```bash
+Сборка переносит их в `build/script/`.
+
+```shell
 ├── build/
 │   ├── js
 │   │   ├── script.js
 │   │   └── modal.js
 ```
 
-## Работа со сторонними библиотеками
-Для удобства внесения сторонних библиотек в ваш проект, вы можете использовать папку vendor. В этой папке вы можете размещать любые файлы, связанные с внешними библиотеками.
+## Работа со сторонними библиотеками
+
+Для удобства внесения сторонних библиотек в ваш проект, вы можете использовать папку `source/vendor/`. В этой папке вы можете размещать любые файлы, связанные с внешними библиотеками.
 
-Например, предположим, что вы хотите добавить в проект библиотеку, которая включает в себя как стилевой файл library.css, так и скрипты library.js. Чтобы интегрировать их в ваш проект, следуйте этим шагам:
+Например, предположим, что вы хотите добавить в проект библиотеку, которая включает в себя как стилевой файл `library.css`, так и скрипты `library.js`. Чтобы интегрировать их в ваш проект, следуйте этим шагам:
 
-Положите файлы библиотеки в папку vendor, как показано ниже:
+Положите файлы библиотеки в папку `source/vendor/`, как показано ниже:
 
-```bash
+```shell
 ├── source/
 │   └── vendor/
 │        ├── library.css
 │        └── library.js
 ```
 
-Если у вас есть несколько библиотек с разными файлами, вы можете группировать файлы одной библиотеки в ее собственную подпапку. Например:
-```bash
+Если у вас есть несколько библиотек с разными файлами, вы можете группировать файлы одной библиотеки в ее собственную подпапку. Например:
+
+```shell
 ├── source/
 │   └── vendor/
 │       └── library/
 │             ├── library.css
 │             └── library.js
 ```
 
-При сборке вашего проекта, все файлы из папки vendor будут включены в папку build, сохраняя их структуру. Например:
-```bash
+При сборке вашего проекта, все файлы из папки `source/vendor/` будут включены в папку `build/vendor/`, сохраняя их структуру. Например:
+
+```shell
 ├── build/
 │   └── vendor/
 │        └── library/
 │             ├── library.css
 │             └── library.js
 ```
 
-Таким образом, вы можете удобно организовать и внедрить сторонние библиотеки в ваш проект, сохраняя их структуру в папке vendor.
+Таким образом, вы можете удобно организовать и внедрить сторонние библиотеки в ваш проект, сохраняя их структуру в папке `source/vendor/`.