LMS/docs/06-authoring.md

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

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

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

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:

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

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

Обычный markdown

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

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

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

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

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

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

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

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

Картинки

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

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

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

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

Видео

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

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

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

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

• Главы, разделы и статьи из архива обновляются (совпадение по главе + разделу + slug статьи).
• Разделы и статьи, которых в архиве нет, но они есть в главах из архива, удаляются — архив считается источником истины (в уведомлении пишется «удалено устаревших: N»).
• Главы, которых нет в архиве совсем, не затрагиваются — их нужно удалить вручную.
• Ссылки вида 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) или публиковать ссылкой на внешний хостинг.