Aerocool Ukraine

Обновлено: 2026-07-10.

Двуязычный маркетинговый и каталоговый сайт Aerocool Украина. Проект собирается статическим генератором Hugo, стилизуется Tailwind CSS и размещается на Netlify.

Основной язык сайта — украинский. Русская версия доступна в каталоге /ru/.

1. Состояние проекта

• Рабочая ветка: dev.
• Тестовый сайт: https://dev--hugo-aerocool.netlify.app/.
• Production-ветка: main.
• Основной домен: https://aerocool.ua/.
• Сборка Netlify пока намеренно использует окружение development.
• Пока действует это окружение, HTML-страницы получают noindex,nofollow. Это защита незавершенного сайта, а не ошибка SEO.
• Включать production-индексацию можно только после прохождения контрольного списка из docs/quality/14-production-quality-gate-2026.md.

2. Стек

Компонент	Текущая версия или роль
Hugo	0.164.0
Node.js	24.16.0
Tailwind CSS	4.3.0
@tailwindcss/cli	4.3.0
Тема Hugo	PaperMod, Git-подмодуль
Хостинг и CI/CD	Netlify
Серверная логика отзывов	Netlify Functions
Хранилище отзывов	Netlify Database / PostgreSQL
Локальный менеджер версий	mise

Начиная с Hugo 0.161.0, функция css.TailwindCSS запускает Tailwind CSS CLI из npm-зависимостей проекта. Поэтому пакеты tailwindcss и @tailwindcss/cli должны оставаться в package.json; отдельный standalone CLI проекту не нужен.

3. Первый локальный запуск

3.1. Что должно быть установлено

• Git;
• mise;
• npm, который поставляется вместе с зафиксированной версией Node.js.

3.2. Подготовка

Из корня репозитория выполните:

mise install
git submodule update --init --recursive
npm install

mise install устанавливает версии Hugo и Node.js из mise.toml. Команда Git загружает тему PaperMod. npm install устанавливает Tailwind CSS, Netlify Database SDK и другие зависимости из lock-файла.

3.3. Запуск сервера

npm run dev

Откройте адрес, который напечатает Hugo, обычно http://localhost:1313/.

Альтернативный сценарий с дополнительными проверками:

./scripts/script_start.sh

Отдельный процесс Tailwind запускать не нужно: Hugo вызывает css.TailwindCSS во время сборки.

4. Структура репозитория

Путь	Назначение
content/	Украинский и русский контент сайта
content/articles/	Статьи в формате Hugo page bundle
content/news/	Новости в формате Hugo page bundle
content/products/	Серии, модели и цветовые варианты товаров
assets/	CSS и ресурсы, которые обрабатывает Hugo Pipes
layouts/	Локальные шаблоны, partials и shortcodes Hugo
data/entities.yaml	Реестр сущностей для schema.org-связей
data/generated/	Сгенерированные данные, включая выгрузку approved-отзывов
static/	Файлы, копируемые в итоговый сайт без обработки
netlify/functions/	Серверные функции Netlify
scripts/	Сборка, проверки и генераторы отчетов
docs/	Рабочие руководства и архив аудитов
docs/XTAL/	Исходные изображения производителя, а не публичная документация
themes/PaperMod/	Тема Hugo как Git-подмодуль
hugo.yaml	Языки, меню, URL, параметры и настройки Hugo
netlify.toml	Сборка, окружение и заголовки Netlify
mise.toml	Зафиксированные локальные версии Hugo и Node.js

Не редактируйте public/ и resources/: это результаты сборки и кэш Hugo.

5. Контент и локализация

Проект использует одну папку страницы для двух языков:

content/articles/example/
├── index.md
├── index.ru.md
└── 01-front.webp

• index.md — украинская версия.
• index.ru.md — русская версия.
• Изображения лежат рядом с контентом и доступны обеим языковым версиям.
• Для разделов применяются _index.md и _index.ru.md.
• При содержательной правке обновляйте обе локализации и поле lastmod.
• Не добавляйте Markdown-заголовок # H1 в тело страницы: видимый H1 создает шаблон.
• Во front matter используется поле schema_types; старое имя schema_type запрещено.

Полный перечень полей находится в docs/content/05-front-matter-reference.md. Готовые основы файлов находятся в docs/content/templates/08-article-template.md — 11-series-template.md.

6. Изображения

Текущий проверенный снимок на 2026-07-10:

• в content/ находится 188 файлов WebP;
• PNG и JPEG в content/ отсутствуют;
• все 12 главных товарных файлов 01-front.webp имеют размер 2000x2000 и разные SHA-256;
• тестовых, placeholder- и candidate-имен в товарных папках не обнаружено.

Основные редакционные стандарты:

Назначение	Исходный размер	Формат
Обложка статьи или новости	1536x1024	WebP
Изображение в теле статьи или новости	обычно 1200x800	WebP
Главное изображение товара	2000x2000	WebP

Hugo создает responsive-варианты при сборке. Не подготавливайте вручную отдельный файл для каждой ширины, если это уже делает шаблон.

Для статьи и новости используйте image и полный блок cover во front matter. Вторичные изображения выводите shortcode seo-image, чтобы получить корректные размеры, srcset, alt, lazy loading и предсказуемое поведение Core Web Vitals.

Полные правила, количество изображений и контроль качества:

• docs/content/06-seo-image-shortcode.md;
• docs/content/34-image-design-playbook-2026.md;
• docs/content/37-page-content-design-dna-2026.md.

docs/XTAL/ хранит оригиналы производителя. Перед публикацией перенесите выбранный материал в page bundle, дайте ему стандартное имя, обработайте и экспортируйте в WebP. Hugo не публикует исходники из docs/XTAL/.

7. Шаблоны и стили

• Локальные изменения делайте в layouts/, а не внутри темы.
• Главный файл CSS — assets/css/main.css.
• Локальные шаблоны имеют расширение .html.
• SEO partials находятся в layouts/_partials/_seo/.
• Schema.org partials находятся в layouts/_partials/_schema/.
• Папку layouts/_default/ не восстанавливайте без отдельной архитектурной причины.

Принципы Hugo lookup order и используемые helpers описаны в docs/architecture/03-hugo-template-helpers.md.

8. Отзывы

Система отзывов разделена на три слоя:

1. netlify/functions/reviews.mjs принимает и проверяет запросы, создает отзывы со статусом pending и читает одобренные записи.
2. scripts/export_reviews.mjs во время сборки выгружает approved-отзывы в data/generated/reviews.json.
3. Hugo показывает только выгруженные публичные отзывы и на их основе может сформировать Review и AggregateRating.

В Netlify должна быть задана секретная переменная REVIEW_EMAIL_HASH_SALT. Ее нельзя хранить в репозитории или в netlify.toml. Подробная настройка, миграции и модерация описаны в docs/deploy/17-netlify-database-reviews.md.

9. SEO, WebMCP и llms.txt

• Видимый текст, canonical URL, hreflang, sitemap и JSON-LD остаются основой доступности контента для поиска.
• static/llms.txt — дополнительная Markdown-карта сайта для LLM/AI-агентов.
• Google Search официально указывает, что llms.txt не требуется и не оказывает положительного или отрицательного влияния на ранжирование. Его нельзя считать SEO-фактором или заменой sitemap.
• WebMCP-аннотации форм — progressive enhancement для совместимых AI-агентов, а не замена HTML-доступности, schema.org или серверной валидации.
• Для чувствительных действий нельзя включать toolautosubmit; пользователь должен подтвердить отправку.

Технический контракт: docs/seo/36-hugo-yaml-serp-technical-contract-2026.md. Профильная проверка: docs/audits/96-2026-07-08-webmcp-llms-agentic-readiness-audit.md.

10. Сборка и проверки

Development-сборка

npm run build

Сначала экспортирует approved-отзывы, затем собирает минимизированный сайт в окружении development.

Production-проверка

npm run build:production

Эта команда нужна для проверки production-HTML. Она не меняет netlify.toml и сама по себе не публикует сайт.

Основной локальный контроль

npm run docs:check
./scripts/script_check.sh
git diff --check

npm run docs:check проверяет нумерацию, H1, даты, карту и локальные ссылки проектной документации.

Отчет по сущностям

После production-сборки:

npm run entity:report

Генератор обновляет docs/seo/32-entity-performance-report-2026.md и связанный CSV.

PageSpeed Insights

Проверку опубликованных URL выполняйте вручную для мобильного и настольного режимов. Локальный Netlify browser-аудит-плагин проект не использует. Пошаговое руководство: docs/quality/13-pagespeed-insights-audit.md.

11. Работа с ветками и Netlify

1. Обычные изменения делайте в dev.
2. Перед push запустите локальные проверки.
3. Проверьте Branch Deploy https://dev--hugo-aerocool.netlify.app/.
4. Переносите изменения в main только как осознанный production-релиз.
5. Перед production включите production-окружение и убедитесь, что индексируемые страницы получают index,follow.

Netlify использует атомарные deploy, но браузерный кэш не очищается новым deploy. Поэтому immutable допустим только для URL с отпечатком содержимого. Правила маршрутизации и кэширования описаны в docs/deploy/16-netlify-routing.md.

12. Маршрут по документации

Начинайте в таком порядке:

1. README.md — понять проект и запустить его.
2. AGENTS.md — изучить обязательные правила изменений.
3. docs/01-documentation-map.md — выбрать последовательность под конкретную задачу.
4. docs/architecture/02-documentation-style-guide.md — понять, как поддерживать сами документы.

Все постоянные руководства имеют номера 01–41. Аудиты 42–98 являются историческими снимками и читаются после рабочих руководств. Текущая итоговая проверка — docs/audits/99-2026-07-10-full-documentation-project-sync-audit-current.md.