# Webpunk Templates — Подробная документация по сборщику

## Быстрый старт

1. **Установите pnpm:**  
   [Инструкция по установке](https://pnpm.io/)

2. **Установите зависимости:**  
   ```bash
   pnpm install
   ```

3. **Запустите сборку или сервер разработки:**  
   - Сборка:  
     ```bash
     pnpm run build
     ```
   - Сервер разработки:  
     ```bash
     pnpm run dev
     ```

---

## Структура проекта

- `src/` — исходные файлы (шаблоны, стили, скрипты, изображения, данные)
- `dist/` — результат сборки (готовый к публикации код)
- `ssl/` — dev SSL-сертификаты (создаются автоматически)
- `.env.local` — локальная конфигурация сборщика

---

## Основные возможности сборщика

### 1. **Гибкая работа с шаблонами**

- Поддержка **Pug** и **Twig** (выбор через `.env.local` или команды)
- Инкрементальная сборка страниц: при изменении страницы пересобирается только она
- Автоматическая подгрузка данных из `src/data/*.json` для шаблонов
- В шаблонах доступны функции для генерации srcset и mime-типов изображений

### 2. **Стили и скрипты**

- SCSS компиляция с sourcemaps, autoprefixer, postcss-url (автоматическое добавление версий к ассетам)
- Минификация CSS (`style.min.css`)
- Сборка и минификация JS (разделение на common/vendor)
- Поддержка sourcemaps для JS

### 3. **Изображения**

- Оптимизация PNG, JPEG, SVG
- Генерация webp и avif-версий изображений
- Инкрементальная обработка (обрабатываются только новые/изменённые файлы)
- Генерация SVG-спрайта и автоматическая инъекция в HTML

### 4. **Автоматизация и наблюдение**

- Watch-режим для всех исходников (шаблоны, данные, стили, скрипты, изображения, иконки)
- При изменении страницы пересобирается только она, при изменении общих файлов — пересобираются все страницы
- Автоматическая перезагрузка браузера через BrowserSync

### 5. **HTTPS для разработки**

- Автоматическое создание самоподписанных SSL-сертификатов для локальной разработки
- Включение HTTPS через `.env.local` или специальные команды

### 6. **Конфигурация**

- Все параметры (шаблонизатор, порт, хост, HTTPS, автооткрытие браузера и др.) настраиваются в `.env.local`
- Быстрое создание и обновление конфигурации через команды

---

## Основные команды

| Команда                | Описание                                                                 |
|------------------------|--------------------------------------------------------------------------|
| `pnpm run dev`         | Запуск сервера разработки (шаблонизатор по умолчанию из `.env.local`)    |
| `pnpm run dev:pug`     | Запуск dev-сервера с Pug                                                 |
| `pnpm run dev:twig`    | Запуск dev-сервера с Twig                                                |
| `pnpm run dev:https`   | Dev-сервер с HTTPS                                                       |
| `pnpm run dev:pug:https` | Dev-сервер с Pug и HTTPS                                               |
| `pnpm run dev:twig:https` | Dev-сервер с Twig и HTTPS                                             |
| `pnpm run build`       | Сборка проекта (шаблонизатор по умолчанию)                               |
| `pnpm run build:pug`   | Сборка с Pug                                                             |
| `pnpm run build:twig`  | Сборка с Twig                                                            |
| `pnpm run ssl:create`  | Создать dev SSL-сертификаты                                              |
| `pnpm run ssl:check`   | Проверить наличие SSL-сертификатов                                       |
| `pnpm run ssl:info`    | Информация о сертификатах                                                |
| `pnpm run ssl:delete`  | Удалить dev SSL-сертификаты                                              |
| `pnpm run data:create` | Создать пример файла данных                                              |
| `pnpm run config:create` | Создать `.env.local` с настройками                                     |
| `pnpm run config:reload` | Перезагрузить конфиг без перезапуска сервера                           |
| `pnpm run clean`       | Очистить папку `dist`                                                    |
| `pnpm run pugprettier:fix` | Применить prettier к pug-файлам                                     |
| `pnpm run stylelint`   | Проверить SCSS на ошибки                                                 |
| `pnpm run stylelint:fix` | Исправить ошибки SCSS автоматически                                    |
| `pnpm run eslint`      | Проверить JS на ошибки                                                   |
| `pnpm run gh-pages`    | Залить содержимое `dist` на GitHub Pages                                |
| `pnpm run public`      | Сборка и публикация на GitHub Pages                                     |

---

## Как работает сборщик

1. **Конфигурация**  
   При запуске читается `.env.local`. Если файла нет — создаётся автоматически.  
   Можно выбрать шаблонизатор, порт, хост, включить HTTPS и др.

2. **Сборка**  
   - Очищается папка `dist`
   - Копируются ассеты (шрифты, изображения, фавиконки, robots.txt и др.)
   - Компилируются стили и скрипты (с минификацией и sourcemaps)
   - Оптимизируются изображения, генерируются webp/avif
   - Генерируется SVG-спрайт
   - Собираются HTML-файлы из шаблонов (Pug или Twig), подставляются данные из JSON
   - В HTML автоматически инъектируется SVG-спрайт

3. **Dev-сервер**  
   - Запускается BrowserSync на выбранном порту/хосте
   - При изменении страницы пересобирается только она (инкрементальная сборка)
   - При изменении общих файлов (layout, mixins, data) пересобираются все страницы
   - При изменении ассетов, стилей, скриптов — пересобираются только они
   - Браузер автоматически перезагружается

4. **HTTPS**  
   - При первом запуске с HTTPS создаются dev-сертификаты (openssl обязателен)
   - Сервер работает по https://

---

## Примеры использования

- **Сменить шаблонизатор:**  
  В `.env.local` изменить `TEMPLATE_ENGINE=pug` или `TEMPLATE_ENGINE=twig`, либо использовать команды `dev:pug`, `dev:twig`, `build:pug`, `build:twig`.

- **Включить HTTPS:**  
  В `.env.local` поставить `HTTPS=true` или использовать команду `dev:https`.

- **Добавить новые данные:**  
  Добавьте JSON-файл в `src/data/`, он автоматически попадёт в шаблоны.

---

## Советы

- Для корректной работы HTTPS нужен установленный openssl.
- Для публикации на GitHub Pages используйте `pnpm run public`.
- Для быстрой генерации структуры данных используйте `pnpm run data:create`.
- Для обновления конфигурации без перезапуска сервера — `pnpm run config:reload`.

---

## Каталоги

- Исходники: `src/`
- Сборка: `dist/`
- Конфиг: `.env.local`
- Сертификаты: `ssl/`