9.7 KiB
AGENTS.md — генератор lab-gen-pptx
lab-gen-pptx собирает презентацию PPTX из обычных Markdown-файлов по
шаблону Самарского университета. Поведение задаётся файлом config.yaml.
1. Требования
- Node.js 18+.
- Зависимости:
pptxgenjs,js-yaml. - Для директив
::: imageс файлами.puml— Java 11+ (берётся изJAVA_HOME, иначеjavaиз PATH) и файлplantuml.jar(см.config.plantuml).
2. Состав
config.yaml # настройки (тема, тексты, таблицы, список слайдов)
content/
slides/*.md # по одному Markdown-файлу на слайд
assets/ # задники (title-bg.jpeg, content-bg.jpg, final-bg.jpeg),
# готовые PNG/JPEG и исходники PlantUML (*.puml)
presentation.pptx # результат сборки (ключ presentation.output)
.plantuml-cache/ # кэш отрендеренных PlantUML (ключ plantuml.cacheDir)
src/ # cli.js, config.js, parse.js, render.js, plantuml.js, build.js
Все относительные пути считаются от каталога config.yaml.
Общий plantuml.jar монорепозитория лежит в корне, в tools/plantuml.jar
(plantuml.jar: ../tools/plantuml.jar). Для автономного дистрибутива положите
tools/plantuml.jar рядом с config.yaml и задайте путь tools/plantuml.jar.
3. Командная строка
lab-gen-pptx [config.yaml] [опции]
-c, --config <file> путь к config.yaml (по умолчанию config.yaml)
-o, --output <file> переопределить имя выходного файла
--check только проверить конфиг и ссылки
-v, --verbose подробный вывод
-h, --help справка
--version версия
npm run check
npm run generate
4. Схема config.yaml
| Раздел | Назначение |
|---|---|
presentation |
output, author, track |
theme |
width/height (дюймы), font, colors, backgrounds, slideNumber |
text |
макеты текста для типов слайдов titleSlide, section, content, final |
table |
размер шрифта, цвета шапки/ячеек/границ |
callout |
плашка-вывод: заливка, рамка, цвета и размеры шрифтов |
metrics |
карточки-метрики: заливка, цвета, размеры значения и подписи |
flow |
нативная схема-цепочка: заливка, рамка, стрелки, размер |
chart |
палитра, размер шрифта, легенда, высота диаграммы |
plantuml |
рендеринг *.puml (см. п. 5) |
content.dir |
каталог контента |
slides |
список слайдов: { type, file } |
Типы слайдов: title, section, content, final. Каждому типу соответствует
макет (slideMaster) с собственным фоном:
| type | Фон | Оформление |
|---|---|---|
title |
title-bg.jpeg |
синий, белый текст в правой половине |
section |
title-bg.jpeg |
разделитель, крупный белый текст справа |
content |
content-bg.jpg |
белый лист, заголовок в верхней синей плашке |
final |
final-bg.jpeg |
синий, белый текст справа |
Номер слайда выводится в правом нижнем углу для content и section.
5. Формат слайда (Markdown)
# Заголовок слайда -> заголовок
## Подзаголовок -> подзаголовок (для title/final)
- пункт списка -> маркер
- вложенный пункт -> вложенный маркер
Обычный абзац. **Жирный** текст, *курсив*, ==выделение== и `код`
поддерживаются в абзацах, пунктах и ячейках таблиц.
::: table
| Столбец A | Столбец B |
|---|---|
| 1 | 2 |
:::
::: image assets/pic.png
подпись под рисунком
:::
::: notes
Заметки докладчика (используются как сценарий выступления).
:::
Богатое форматирование текста
В абзацах, пунктах списка и ячейках таблиц работает inline-разметка:
| Разметка | Результат |
|---|---|
**текст** |
полужирный |
*текст* |
курсив |
==текст== |
акцентный (брендовый) полужирный |
`текст` |
моноширинный (Consolas) |
Пункты списка рисуются с висячим отступом, поэтому многострочные пункты с форматированием сохраняют маркер и выравнивание.
Директива ::: callout "Заголовок"
Плашка-вывод с заливкой и рамкой. Внутри — абзацы и/или пункты списка:
::: callout "Итог"
Рынок проверяется ==дешёвым инкрементом==, а не дорогим запуском.
:::
Параметр side=left|right ставит плашку в левую или правую колонку слайда.
Если у слайда есть блоки с side, они верстаются в две колонки (левая/правая),
а остальные блоки — как обычно. Типовое сочетание: ::: image ... side=left
и ::: callout ... side=right.
Директива ::: metrics
Карточки-метрики (до четырёх). Каждая строка — Значение | Подпись
(допускается разделитель —):
::: metrics
70% | новых товаров уходят с рынка
10 | сфер применения метода
:::
Директива ::: flow
Нативная схема-цепочка из скруглённых блоков со стрелками. Шаги разделяются
-> (или →), можно писать по одному на строку:
::: flow
Sprint Planning -> Спринт -> Sprint Review -> Ретроспектива
:::
Если ширина блока становится малой, схема автоматически разворачивается вертикально.
Директива ::: chart <тип> "Заголовок"
Диаграмма на основе GFM-таблицы: первая колонка — категории, остальные —
числовые ряды (заголовки колонок = имена рядов). Поддерживаемые типы:
bar, bar3d, line, pie, doughnut, area, radar, scatter.
::: chart doughnut "Новинки, которые не выживают"
| Итог | Доля, % |
|---|---|
| Успешные новинки | 30 |
| Уходят с рынка | 70 |
:::
Директива ::: image и PlantUML
file — относительно content.dir (content/). Если файл оканчивается на
.puml (.plantuml, .pu, .iuml), он рендерится в PNG через plantuml.jar
(см. config.plantuml) и вставляется как обычный рисунок:
::: image assets/scrum-cycle.puml height=3.2
Цикл Scrum: от Product Backlog до масштабирования товара
:::
Подпись (строка под директивой) выводится под рисунком курсивом. Растровые
PNG/JPEG вставляются как есть. Необязательный параметр height=<дюймы>
(h=) ограничивает высоту рисунка, чтобы уместить под ним другие блоки;
пропорции сохраняются, рисунок центрируется. Параметр side=left|right
ставит рисунок в колонку (см. ::: callout).
6. Задники
Изображения-задники извлечены из presentation_16.pptx в
content/assets/ (title-bg.jpeg, content-bg.jpg, final-bg.jpeg). При замене
шаблона положите новые файлы и обновите пути в theme.backgrounds.
7. Шрифт
В шаблоне используется фирменный Elektra Text Pro, который обычно не установлен
в системе (иначе Word подставляет случайный шрифт). Поэтому по умолчанию задан
Segoe UI — близкий современный sans. Альтернативы: Calibri, Candara,
Corbel, Noto Sans, Arial. Смените theme.font при необходимости.
8. Проверка результата
Презентацию можно отрендерить для визуальной проверки через LibreOffice:
soffice --headless --convert-to pdf --outdir . presentation.pptx