161 lines
9.3 KiB
Markdown
161 lines
9.3 KiB
Markdown
# 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/`
|