mirror of
https://github.com/StepanovPlaton/SSAUGenerator.git
synced 2026-10-31 10:18:29 +04:00
StepanovPlaton
bf7816ab7c
- Move projects into content/<project>/{docx,pptx} with shared assets/
- Flatten config paths; output = project name in project folder
- Add pptx --init scaffold; remove docx exe build
- Add feature-complete content/example; ignore content/* except example
- Rewrite README and AGENTS.md
240 lines
11 KiB
Markdown
240 lines
11 KiB
Markdown
# 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 версия
|
||
```
|
||
|
||
Типичный цикл:
|
||
|
||
```powershell
|
||
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)
|
||
|
||
```md
|
||
# Заголовок слайда -> заголовок
|
||
## Подзаголовок -> подзаголовок (для title/final)
|
||
|
||
- пункт списка -> маркер
|
||
- вложенный пункт -> вложенный маркер
|
||
|
||
Обычный абзац. **Жирный** текст, *курсив*, ==выделение== и `код`
|
||
поддерживаются в абзацах, пунктах и ячейках таблиц.
|
||
|
||
::: table
|
||
| Столбец A | Столбец B |
|
||
|---|---|
|
||
| 1 | 2 |
|
||
:::
|
||
|
||
::: image ../assets/images/pic.png
|
||
подпись под рисунком
|
||
:::
|
||
|
||
::: notes
|
||
Заметки докладчика (используются как сценарий выступления).
|
||
:::
|
||
```
|
||
|
||
### Богатое форматирование текста
|
||
|
||
В абзацах, пунктах списка и ячейках таблиц работает inline-разметка:
|
||
|
||
| Разметка | Результат |
|
||
|---|---|
|
||
| `**текст**` | полужирный |
|
||
| `*текст*` | курсив |
|
||
| `==текст==` | акцентный (брендовый) полужирный |
|
||
| `` `текст` `` | моноширинный (Consolas) |
|
||
|
||
Пункты списка рисуются с висячим отступом, поэтому многострочные пункты с
|
||
форматированием сохраняют маркер и выравнивание.
|
||
|
||
### Директива `::: callout "Заголовок"`
|
||
|
||
Плашка-вывод с заливкой и рамкой. Внутри — абзацы и/или пункты списка:
|
||
|
||
```md
|
||
::: callout "Итог"
|
||
Рынок проверяется ==дешёвым инкрементом==, а не дорогим запуском.
|
||
:::
|
||
```
|
||
|
||
Параметр `side=left|right` ставит плашку в левую или правую колонку слайда.
|
||
Если у слайда есть блоки с `side`, они верстаются в две колонки, а остальные
|
||
блоки — как обычно. Не смешивайте на одном слайде обычный текст и колонки
|
||
(`side`) — они накладываются.
|
||
|
||
### Директива `::: 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`. Если файл оканчивается на `.puml`
|
||
(`.plantuml`, `.pu`, `.iuml`), он рендерится в PNG через `plantuml.jar` и
|
||
вставляется как обычный рисунок:
|
||
|
||
```md
|
||
::: 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:
|
||
|
||
```powershell
|
||
soffice --headless --convert-to pdf --outdir . presentation.pptx
|
||
```
|