142 lines
9.4 KiB
Markdown
142 lines
9.4 KiB
Markdown
# Как оформлять учебные материалы
|
||
|
||
Материалы лежат в файлах, а на сервер попадают **импортом 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>`). Работает и обычная
|
||
вставка ``, но тогда подписи не будет.
|
||
|
||
Поддерживаются `png`, `jpg`, `jpeg`, `gif`, `svg`, `webp` — до **10 МБ** на файл.
|
||
|
||
## Видео
|
||
|
||
Видеофайл также кладётся в `assets/`, вставка — директивой:
|
||
|
||
```markdown
|
||
:::video assets/demo-install.mp4 | Видео: установка и первая программа
|
||
```
|
||
|
||
На странице появится проигрыватель с элементами управления; подпись необязательна.
|
||
Поддерживаются `mp4` (рекомендуется, кодек H.264), `webm`, `ogg` — до **100 МБ** на файл.
|
||
Плеер поддерживает перемотку (сервер отдаёт файл частями).
|
||
|
||
## Правка прямо на страницах материалов
|
||
|
||
Администратору доступны действия не только на главной `/learn`, но и на каждой странице:
|
||
|
||
* **статья** — «Править» (правка прямо на странице: текст статьи открывается в редакторе
|
||
с панелью форматирования — жирный, курсив, заголовки, списки, ссылки, код, таблицы,
|
||
картинки, видео, спойлер), «Скрыть/Опубликовать», «Удалить», а также навигация
|
||
**← предыдущая / следующая →** (работает и между разделами) и **боковое содержание**
|
||
со всеми главами, разделами и статьями;
|
||
* **раздел** — «+ Статья», «Переименовать раздел», «Скрыть/Опубликовать»,
|
||
«Перенести статьи и удалить», «Удалить раздел»; у каждой статьи в списке — «Править»
|
||
(открывает статью с готовым окном правки), скрытие и удаление;
|
||
* **глава** — «+ Раздел», «Переименовать главу», «Скрыть/Опубликовать», «Удалить главу»;
|
||
у каждого раздела — переименование, скрытие, перенос статей и удаление, у каждой статьи — «Править».
|
||
|
||
Порядок меняется перетаскиванием за значок **⠿** (сохраняется сразу, без перезагрузки страницы):
|
||
на главной `/learn` — главы, разделы и статьи (в том числе перенос раздела в другую главу и
|
||
статьи в другой раздел), на **странице главы** — разделы этой главы и статьи внутри них,
|
||
на **странице раздела** — статьи этого раздела.
|
||
|
||
## Импорт: что происходит с материалами
|
||
|
||
* Главы, разделы и статьи из архива **обновляются**. Совпадение ищется **по названию**
|
||
(глава — по названию главы, раздел — по названию раздела внутри главы, статья — по названию
|
||
внутри раздела); если по названию не нашли, для совместимости проверяется slug. Поэтому один
|
||
и тот же материал, созданный вручную и загруженный из архива, не дублируется.
|
||
* Номера в именах каталогов архива (`02-Матрицы`, `01-Двумерные массивы`) задают только
|
||
**порядок** (позицию). В адрес страницы они не попадают: slug формируется из названия, как и
|
||
при ручном создании (`Матрицы` → `matricy`, `Функции` → `funkcii`).
|
||
* Режим **синхронизации** (галка в форме импорта) дополнительно **удаляет** разделы и статьи
|
||
главы, которых нет в архиве — архив считается источником истины («удалено устаревших: 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`)
|
||
или публиковать ссылкой на внешний хостинг.
|