Rename project to SSAU Generator and restructure content

- 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
2026-10-31 10:18:29 +04:00 · 2026-10-11 23:25:22 +04:00
parent 35611e2a91
commit bf7816ab7c
80 changed files with 1166 additions and 3432 deletions
--- a/pptx/AGENTS.md
+++ b/pptx/AGENTS.md
@@ -1,66 +1,94 @@
-# AGENTS.md — генератор lab-gen-pptx
+# AGENTS.md — работа с презентацией PPTX

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

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

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

-## 2. Состав
+## 2. Раскладка проекта
+
+Проект лежит в `content/<проект>/pptx/` рядом с `config.yaml`:

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

-Общий `plantuml.jar` монорепозитория лежит в корне, в `tools/plantuml.jar`
-(`plantuml.jar: ../tools/plantuml.jar`). Для автономного дистрибутива положите
-`tools/plantuml.jar` рядом с `config.yaml` и задайте путь `tools/plantuml.jar`.
+Презентация собирается в папку проекта и называется по имени проекта:
+`content/<проект>/<проект>.pptx`. Значение ключа `presentation.output` при такой
+раскладке — `../<проект>.pptx`.
+
+Структуру проекта создавайте командой `--init`: она формирует `config.yaml`,
+примеры слайдов и общий каталог `content/<проект>/assets/` (задники), который
+используется и генератором `docx`.
+
+Готовый пример со всеми возможностями — `content/example/pptx/`.

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

+Из корня репозитория:
+
 ```
-lab-gen-pptx [config.yaml] [опции]
+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
-npm run check
-npm run generate
+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` |
+| `text` | макеты текста для типов `titleSlide`, `section`, `content`, `final` |
 | `table` | размер шрифта, цвета шапки/ячеек/границ |
 | `callout` | плашка-вывод: заливка, рамка, цвета и размеры шрифтов |
 | `metrics` | карточки-метрики: заливка, цвета, размеры значения и подписи |
-| `flow` | нативная схема-цепочка: заливка, рамка, стрелки, размер |
+| `flow` | схема-цепочка: заливка, рамка, стрелки, размер |
 | `chart` | палитра, размер шрифта, легенда, высота диаграммы |
 | `plantuml` | рендеринг `*.puml` (см. п. 5) |
-| `content.dir` | каталог контента |
+| `content.dir` | каталог контента (по умолчанию `.`) |
 | `slides` | список слайдов: `{ type, file }` |

 Типы слайдов: `title`, `section`, `content`, `final`. Каждому типу соответствует
@@ -93,7 +121,7 @@ npm run generate
 | 1 | 2 |
 :::

-::: image assets/pic.png
+::: image ../assets/images/pic.png
 подпись под рисунком
 :::

@@ -127,9 +155,9 @@ npm run generate
 ```

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

 ### Директива `::: metrics`

@@ -145,8 +173,7 @@ npm run generate

 ### Директива `::: flow`

-Нативная схема-цепочка из скруглённых блоков со стрелками. Шаги разделяются
-`->` (или `→`), можно писать по одному на строку:
+Схема-цепочка из скруглённых блоков со стрелками. Шаги разделяются `->` (или `→`):

 ```md
 ::: flow
@@ -154,14 +181,14 @@ Sprint Planning -> Спринт -> Sprint Review -> Ретроспектива
 :::
 ```

-Если ширина блока становится малой, схема автоматически разворачивается
+Если блоки становятся слишком узкими, схема автоматически разворачивается
 вертикально.

 ### Директива `::: chart <тип> "Заголовок"`

 Диаграмма на основе GFM-таблицы: первая колонка — категории, остальные —
-числовые ряды (заголовки колонок = имена рядов). Поддерживаемые типы:
-`bar`, `bar3d`, `line`, `pie`, `doughnut`, `area`, `radar`, `scatter`.
+числовые ряды (заголовки колонок = имена рядов). Типы: `bar`, `bar3d`, `line`,
+`pie`, `doughnut`, `area`, `radar`, `scatter`.

 ```md
 ::: chart doughnut "Новинки, которые не выживают"
@@ -174,38 +201,38 @@ Sprint Planning -> Спринт -> Sprint Review -> Ретроспектива

 ### Директива `::: image` и PlantUML

-`file` — относительно `content.dir` (`content/`). Если файл оканчивается на
-`.puml` (`.plantuml`, `.pu`, `.iuml`), он рендерится в PNG через `plantuml.jar`
-(см. `config.plantuml`) и вставляется как обычный рисунок:
+`file` — относительно `content.dir`. Если файл оканчивается на `.puml`
+(`.plantuml`, `.pu`, `.iuml`), он рендерится в PNG через `plantuml.jar` и
+вставляется как обычный рисунок:

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

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

 ## 6. Задники

-Изображения-задники извлечены из `presentation_16.pptx` в
-`content/assets/` (`title-bg.jpeg`, `content-bg.jpg`, `final-bg.jpeg`). При замене
-шаблона положите новые файлы и обновите пути в `theme.backgrounds`.
+Задники лежат в общем каталоге ресурсов проекта
+(`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` при необходимости.
+В исходном шаблоне используется фирменный `Elektra Text Pro`, который обычно не
+установлен в системе. Поэтому по умолчанию задан `Segoe UI` — близкий современный
+sans. Альтернативы: `Calibri`, `Candara`, `Corbel`, `Noto Sans`, `Arial`.
+Смените `theme.font` при необходимости.

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

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

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