# Создание темы

Тема отвечает за оформление фронта. Это папка `templates/<slug>/` с манифестом `theme.json` и набором `.tpl`-файлов. PHP в шаблонах запрещён — только [теги шаблонизатора](/docs/code/templating).

## Быстрый старт: пустая тема

Не пишите с нуля — скачайте готовый скелет:

**[Скачать пустую тему (zip)](/public/assets/plugins/handbook/celena-starter-theme.zip)**

Внутри: `theme.json`, `_partials/head.tpl` и `foot.tpl`, базовые `home.tpl`, `page.tpl`, `news_list.tpl`, `news_full.tpl`, `search.tpl`, `404.tpl` и `assets/theme.css`. Распакуйте так, чтобы папка `starter-theme/` оказалась в `templates/`, активируйте тему в **Настройки → Шаблоны** и переименуйте под себя (папку и `slug` в `theme.json`).

## theme.json

```json
{
  "name": "My Theme",
  "slug": "mytheme",
  "version": "1.0.0",
  "author": "Имя автора",
  "description": "Краткое описание",
  "regions": ["header", "main", "footer"]
}
```

`slug` совпадает с именем папки и используется в опции `theme`.

## Минимальный комплект шаблонов

| Файл | Когда вызывается |
|------|------------------|
| `home.tpl` | главная страница |
| `page.tpl` | статическая страница `/p/{slug}` |
| `news_list.tpl` | список новостей/категории/поиска |
| `news_full.tpl` | страница одной новости |
| `search.tpl` | результаты поиска |
| `404.tpl` | страница «не найдено» |

Плюс переиспользуемые куски в `_partials/` (например `head.tpl`, `header.tpl`, `footer.tpl`) и ассеты в `assets/`.

## Быстрый старт «своя тема за час»

1. Скопируйте `templates/default/` → `templates/mytheme/`.
2. Поправьте `theme.json`.
3. Замените стили в `assets/theme.css`.
4. Перепишите `_partials/head.tpl` и подвал под свою вёрстку.
5. При необходимости переопределите `home.tpl`, `news_list.tpl`, `news_full.tpl`, `page.tpl`.
6. Активируйте тему в **Настройки → Шаблоны**.
7. Проверьте адаптивность и тёмную тему.

## Подключение ассетов и версионирование

Все css/js кладите в `templates/<slug>/assets/` (внешние CDN запрещены политикой CSP). Подключение — в `_partials/head.tpl`:

```html
<link rel="stylesheet" href="/templates/mytheme/assets/theme.css?v=1">
<script src="/templates/mytheme/assets/theme.js?v=1" defer></script>
```

> На проде `nginx` кеширует статику надолго. После правки `.css`/`.js` **увеличивайте версию** (`?v=1` → `?v=2`), иначе вернувшиеся посетители получат старый файл из кеша.

## Тёмная тема

Темы наследуют CSS-переменные ядра (`--bg`, `--surface`, `--text`, `--accent` и т.д.). Тёмный режим включается атрибутом `data-theme="dark"` на `<html>`. Кнопки переключения:

```html
<button data-celena-theme="light">☀</button>
<button data-celena-theme="dark">☾</button>
<button data-celena-theme="auto">A</button>
```

## Переопределение шаблонов плагина

Тема может перебить любой шаблон плагина, не трогая сам плагин. Достаточно создать файл по пути:

```
templates/<mytheme>/plugins/<slug>/<путь>.tpl
```

Движok ищет шаблон плагина в порядке: оверрайд активной темы → оверрайд default-темы → оригинал плагина. Удалите файл темы — вернётся оригинал. Подробнее — [Создание плагина](/docs/code/plugin-create).

## Кеш шаблонов

После правки `.tpl` на проде очистите кеш скомпилированных шаблонов (`storage/cache/tpl/*`) — иначе отдастся старая версия. Локально кеш сам инвалидируется по mtime; в админке есть **Настройки → Производительность → Очистить кеш**.
