mirror of
https://github.com/StepanovPlaton/SSAUGenerator.git
synced 2026-10-31 10:18:29 +04:00
add pptx
This commit is contained in:
212
pptx/AGENTS.md
Normal file
212
pptx/AGENTS.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# 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 версия
|
||||
```
|
||||
|
||||
```powershell
|
||||
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)
|
||||
|
||||
```md
|
||||
# Заголовок слайда -> заголовок
|
||||
## Подзаголовок -> подзаголовок (для title/final)
|
||||
|
||||
- пункт списка -> маркер
|
||||
- вложенный пункт -> вложенный маркер
|
||||
|
||||
Обычный абзац. **Жирный** текст, *курсив*, ==выделение== и `код`
|
||||
поддерживаются в абзацах, пунктах и ячейках таблиц.
|
||||
|
||||
::: table
|
||||
| Столбец A | Столбец B |
|
||||
|---|---|
|
||||
| 1 | 2 |
|
||||
:::
|
||||
|
||||
::: image assets/pic.png
|
||||
подпись под рисунком
|
||||
:::
|
||||
|
||||
::: notes
|
||||
Заметки докладчика (используются как сценарий выступления).
|
||||
:::
|
||||
```
|
||||
|
||||
### Богатое форматирование текста
|
||||
|
||||
В абзацах, пунктах списка и ячейках таблиц работает inline-разметка:
|
||||
|
||||
| Разметка | Результат |
|
||||
|---|---|
|
||||
| `**текст**` | полужирный |
|
||||
| `*текст*` | курсив |
|
||||
| `==текст==` | акцентный (брендовый) полужирный |
|
||||
| `` `текст` `` | моноширинный (Consolas) |
|
||||
|
||||
Пункты списка рисуются с висячим отступом, поэтому многострочные пункты с
|
||||
форматированием сохраняют маркер и выравнивание.
|
||||
|
||||
### Директива `::: callout "Заголовок"`
|
||||
|
||||
Плашка-вывод с заливкой и рамкой. Внутри — абзацы и/или пункты списка:
|
||||
|
||||
```md
|
||||
::: callout "Итог"
|
||||
Рынок проверяется ==дешёвым инкрементом==, а не дорогим запуском.
|
||||
:::
|
||||
```
|
||||
|
||||
Параметр `side=left|right` ставит плашку в левую или правую колонку слайда.
|
||||
Если у слайда есть блоки с `side`, они верстаются в две колонки (левая/правая),
|
||||
а остальные блоки — как обычно. Типовое сочетание: `::: image ... side=left`
|
||||
и `::: callout ... side=right`.
|
||||
|
||||
### Директива `::: metrics`
|
||||
|
||||
Карточки-метрики (до четырёх). Каждая строка — `Значение | Подпись`
|
||||
(допускается разделитель `—`):
|
||||
|
||||
```md
|
||||
::: metrics
|
||||
70% | новых товаров уходят с рынка
|
||||
10 | сфер применения метода
|
||||
:::
|
||||
```
|
||||
|
||||
### Директива `::: flow`
|
||||
|
||||
Нативная схема-цепочка из скруглённых блоков со стрелками. Шаги разделяются
|
||||
`->` (или `→`), можно писать по одному на строку:
|
||||
|
||||
```md
|
||||
::: flow
|
||||
Sprint Planning -> Спринт -> Sprint Review -> Ретроспектива
|
||||
:::
|
||||
```
|
||||
|
||||
Если ширина блока становится малой, схема автоматически разворачивается
|
||||
вертикально.
|
||||
|
||||
### Директива `::: chart <тип> "Заголовок"`
|
||||
|
||||
Диаграмма на основе GFM-таблицы: первая колонка — категории, остальные —
|
||||
числовые ряды (заголовки колонок = имена рядов). Поддерживаемые типы:
|
||||
`bar`, `bar3d`, `line`, `pie`, `doughnut`, `area`, `radar`, `scatter`.
|
||||
|
||||
```md
|
||||
::: chart doughnut "Новинки, которые не выживают"
|
||||
| Итог | Доля, % |
|
||||
|---|---|
|
||||
| Успешные новинки | 30 |
|
||||
| Уходят с рынка | 70 |
|
||||
:::
|
||||
```
|
||||
|
||||
### Директива `::: image` и PlantUML
|
||||
|
||||
`file` — относительно `content.dir` (`content/`). Если файл оканчивается на
|
||||
`.puml` (`.plantuml`, `.pu`, `.iuml`), он рендерится в PNG через `plantuml.jar`
|
||||
(см. `config.plantuml`) и вставляется как обычный рисунок:
|
||||
|
||||
```md
|
||||
::: 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:
|
||||
|
||||
```powershell
|
||||
soffice --headless --convert-to pdf --outdir . presentation.pptx
|
||||
```
|
||||
Reference in New Issue
Block a user