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

Материалы лежат в файлах, а на сервер попадают импортом 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 МБ на файл. Плеер поддерживает перемотку (сервер отдаёт файл частями).

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

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

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

На странице статьи боковое содержание: на десктопе закреплено (своя прокрутка), на мобильных открывается кнопкой «Содержание» справа. На главной /learn на мобильных три кнопки («+ Статья», «+ Глава», «Импорт zip») идут под заголовком в один ряд.

Порядок меняется перетаскиванием за значок ⠿ (сохраняется сразу, без перезагрузки страницы): на главной /learn — главы, разделы и статьи (в том числе перенос раздела в другую главу и статьи в другой раздел), на странице главы — разделы этой главы и статьи внутри них, на странице раздела — статьи этого раздела.

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

Главы, разделы и статьи из архива обновляются. Совпадение ищется по названию (глава — по названию главы, раздел — по названию раздела внутри главы, статья — по названию внутри раздела); если по названию не нашли, для совместимости проверяется slug. Поэтому один и тот же материал, созданный вручную и загруженный из архива, не дублируется.
Номера в именах каталогов архива (02-Матрицы, 01-Двумерные массивы) задают только порядок (позицию). В адрес страницы они не попадают: slug формируется из названия, как и при ручном создании (Матрицы → matricy, Функции → funkcii).
Режим синхронизации (галка в форме импорта) дополнительно удаляет разделы и статьи главы, которых нет в архиве — архив считается источником истины («удалено устаревших: N»).
Без галки импорт работает в режиме merge: только добавляет и обновляет то, что есть в архиве. Так можно догрузить отдельные статьи, не затрагивая правки, сделанные в приложении.
Главы, которых нет в архиве совсем, не затрагиваются — их нужно удалить вручную.
Минимальный архив (например, только один раздел + assets/) безопасно импортировать в режиме merge: остальные материалы останутся как есть.
Ссылки вида assets/имя автоматически заменяются на адрес /api/v1/content/assets/...; сами файлы складываются в хранилище. Для курсовых статей этот адрес требует сессию пользователя курса, для публичных ALL-материалов остаётся публичным. Файл без привязки к статье больше не публичен: обычные пользователи получают 404, админ — файл и его имя в GET /api/v1/content/legacy-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) или публиковать ссылкой на внешний хостинг.

10 KiB Raw Blame History Unescape Escape