SSAUGenerator/pptx/AGENTS.md

AGENTS.md — работа с презентацией PPTX

Генератор pptx/ собирает презентацию PPTX из обычных Markdown-файлов по шаблону Самарского университета. Этот файл — инструкция агенту по созданию и правке конкретной презентации. Поведение задаётся config.yaml проекта, менять код генератора не нужно.

1. Требования

• Node.js 18+, зависимости ставятся командой npm install в папке pptx/.
• Зависимости: pptxgenjs, js-yaml.
• Для директив ::: image с файлами .puml — Java 11+ (из JAVA_HOME, иначе java из PATH) и файл plantuml.jar (см. config.plantuml).

2. Раскладка проекта

Проект лежит в content/<проект>/pptx/ рядом с config.yaml:

content/<проект>/
├── assets/               # общие ресурсы проекта (общие с docx)
│   ├── title-bg.jpeg     # задники
│   ├── content-bg.jpg
│   ├── final-bg.jpeg
│   └── images/           # готовые PNG/JPEG и исходники .puml
└── pptx/
    ├── config.yaml
    └── slides/
        ├── 00-title.md
        └── 01-*.md

Все относительные пути считаются от каталога config.yaml. Общие с документом ресурсы указывайте через ../assets (например, backgrounds.title: ../assets/title-bg.jpeg). Каталог контента — ключ content.dir (по умолчанию . — папка самого config.yaml).

Презентация собирается в папку проекта и называется по имени проекта: content/<проект>/<проект>.pptx. Значение ключа presentation.output при такой раскладке — ../<проект>.pptx.

Структуру проекта создавайте командой --init: она формирует config.yaml, примеры слайдов и общий каталог content/<проект>/assets/ (задники), который используется и генератором docx.

Готовый пример со всеми возможностями — content/example/pptx/.

3. Командная строка

Из корня репозитория:

node pptx/src/cli.js [config.yaml] [опции]

  -c, --config <file>   путь к config.yaml (по умолчанию config.yaml)
  -o, --output <file>   переопределить имя выходного файла
      --check           только проверить конфиг и ссылки
      --init            создать шаблон config.yaml/slides/assets и выйти
  -v, --verbose         подробный вывод
  -h, --help            справка
      --version         версия

Типичный цикл:

node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --init    # создать структуру проекта
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --check   # проверить
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml           # собрать

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

Если config.yaml не найден, инструмент сам создаёт шаблон (config.yaml, примеры слайдов и общий assets/) и завершается.

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/images/pic.png
подпись под рисунком
:::

::: notes
Заметки докладчика (используются как сценарий выступления).
:::

Богатое форматирование текста

В абзацах, пунктах списка и ячейках таблиц работает inline-разметка:

Разметка	Результат
**текст**	полужирный
*текст*	курсив
==текст==	акцентный (брендовый) полужирный
`текст`	моноширинный (Consolas)

Пункты списка рисуются с висячим отступом, поэтому многострочные пункты с форматированием сохраняют маркер и выравнивание.

Директива ::: callout "Заголовок"

Плашка-вывод с заливкой и рамкой. Внутри — абзацы и/или пункты списка:

::: callout "Итог"
Рынок проверяется ==дешёвым инкрементом==, а не дорогим запуском.
:::

Параметр side=left|right ставит плашку в левую или правую колонку слайда. Если у слайда есть блоки с side, они верстаются в две колонки, а остальные блоки — как обычно. Не смешивайте на одном слайде обычный текст и колонки (side) — они накладываются.

Директива ::: 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. Если файл оканчивается на .puml (.plantuml, .pu, .iuml), он рендерится в PNG через plantuml.jar и вставляется как обычный рисунок:

::: image ../assets/images/scrum-cycle.puml height=3.2
Цикл Scrum: от Product Backlog до масштабирования товара
:::

Подпись (строка под директивой) выводится под рисунком курсивом. Растровые PNG/JPEG вставляются как есть. Параметр height=<дюймы> (h=) ограничивает высоту рисунка (пропорции сохраняются, рисунок центрируется). side=left|right ставит рисунок в колонку.

6. Задники

Задники лежат в общем каталоге ресурсов проекта (content/<проект>/assets/: title-bg.jpeg, content-bg.jpg, final-bg.jpeg). При замене шаблона положите новые файлы и обновите пути в theme.backgrounds.

7. Шрифт

В исходном шаблоне используется фирменный Elektra Text Pro, который обычно не установлен в системе. Поэтому по умолчанию задан Segoe UI — близкий современный sans. Альтернативы: Calibri, Candara, Corbel, Noto Sans, Arial. Смените theme.font при необходимости.

8. Проверка результата

--check проверяет конфиг и наличие слайдов/ресурсов. Презентацию можно отрендерить для визуальной проверки через LibreOffice:

soffice --headless --convert-to pdf --outdir . presentation.pptx