# Как оформлять учебные материалы

Материалы лежат в файлах, а на сервер попадают **импортом ZIP** (админка → `/learn` →
«Импорт zip»). Этот документ — для автора: какой markdown поддерживается, как вставлять
картинки и видео, какие есть ограничения.

## Структура архива

```text
chapters/01-Справочная информация/01-Среда разработки/01-Какую среду выбрать.md
chapters/02-Основы языка C/01-Ввод-вывод и типы/01-Типы данных и ввод-вывод.md
assets/choose-01.svg          # картинки и видео — в корне архива, в папке assets/
assets/demo-install.mp4
```

* `chapters/<NN-глава>/<NN-раздел>/<NN-статья>.md` — три уровня обязательны;
  число в начале имени задаёт порядок.
* В начале файла — front-matter с заголовком и (необязательно) slug:

```markdown
---
title: "Qt Creator: установка и настройка в Windows"
slug: "qt-creator-windows"
---
```

* Если slug не указать, он сгенерируется из названия. Менять slug у существующей статьи
  не стоит — изменится адрес страницы.

## Обычный markdown

Поддерживаются заголовки `##`, списки, таблицы, цитаты (`>`), ссылки, `**жирный**`,
`*курсив*`, блоки кода с указанием языка и сноски.

````markdown
| Клавиши | Действие |
|---|---|
| `Ctrl+R` | собрать и запустить |

```c
int main(void) { return 0; }
```

```bash
gcc -Wall -g main.c -o main
```
````

Код в блоках подсвечивается автоматически (нужен язык после открывающих ```).

## Спойлер (скрытый текст)

Удобно для решений задач: студент видит условие, а решение открывает по клику.

````markdown
:::spoiler Решение
```c
printf("Ответ: 42\n");
```
:::
````

## Картинки

Картинки кладите в `assets/` архива и вставляйте **директивой с подписью**:

```markdown
:::figure assets/qtw-01.svg | Рис. 1. Скачивание установщика
```

Получится оформленный рисунок с подписью (`<figure><img><figcaption>`). Работает и обычная
вставка `![Рис. 1](assets/qtw-01.svg)`, но тогда подписи не будет.

Поддерживаются `png`, `jpg`, `jpeg`, `gif`, `svg`, `webp` — до **10 МБ** на файл.

## Видео

Видеофайл также кладётся в `assets/`, вставка — директивой:

```markdown
:::video assets/demo-install.mp4 | Видео: установка и первая программа
```

На странице появится проигрыватель с элементами управления; подпись необязательна.
Поддерживаются `mp4` (рекомендуется, кодек H.264), `webm`, `ogg` — до **100 МБ** на файл.
Плеер поддерживает перемотку (сервер отдаёт файл частями).

## Правка прямо на страницах материалов

Администратору доступны действия не только на главной `/learn`, но и на каждой странице:

* **статья** — «Править» (модальное окно с markdown), «Скрыть/Опубликовать», «Удалить»,
  а также навигация **← предыдущая / следующая →** (работает и между разделами) и
  **боковое содержание** со всеми главами, разделами и статьями;
* **раздел** — «+ Статья», «Переименовать раздел», «Скрыть/Опубликовать»,
  «Перенести статьи и удалить», «Удалить раздел»; у каждой статьи в списке — «Править»
  (открывает статью с готовым окном правки), скрытие и удаление;
* **глава** — «+ Раздел», «Переименовать главу», «Скрыть/Опубликовать», «Удалить главу»;
  у каждого раздела — переименование, скрытие, перенос статей и удаление, у каждой статьи — «Править».

## Импорт: что происходит с материалами

* Главы, разделы и статьи из архива **обновляются** (совпадение по главе + разделу + slug статьи).
* Режим **синхронизации** (галка в форме импорта) дополнительно **удаляет** разделы и статьи
  главы, которых нет в архиве — архив считается источником истины («удалено устаревших: N»).
* Без галки импорт работает в режиме **merge**: только добавляет и обновляет то, что есть
  в архиве. Так можно догрузить отдельные статьи, **не затрагивая правки, сделанные в приложении**.
* Главы, которых нет в архиве совсем, не затрагиваются — их нужно удалить вручную.
* Минимальный архив (например, только один раздел + `assets/`) безопасно импортировать
  в режиме merge: остальные материалы останутся как есть.
* Ссылки вида `assets/имя` автоматически заменяются на публичный адрес
  `/api/v1/content/assets/...`; сами файлы складываются в хранилище.

## Публикация и скрытие

У каждой главы, раздела и статьи в `/learn` есть кнопка **«Скрыть…»/«Опубликовать…»** и
бейдж «скрыто». Скрытые материалы видны только администратору (со значком), студенты и
гости их не видят; прямые ссылки на скрытое отдают «не найдено». Удобно готовить материал
постепенно.

## Практические советы по медиа

* Скриншоты: PNG или SVG, ширина 960–1400 px; обрезайте лишнее, выделяйте важное рамкой.
* Скринкасты: 1280×720, 30 fps, H.264, до 1–2 минут — так файл остаётся в пределах 50 МБ.
* Имена файлов — латиницей и уникально: `qtw-01.svg`, `vsw-02.svg`, `demo-install.mp4`.
  Одинаковые имена в разных главах перекрывают друг друга.
* Большие видео лучше сжимать (`ffmpeg -i in.mov -vcodec libx264 -crf 28 -preset veryfast out.mp4`)
  или публиковать ссылкой на внешний хостинг.