SSAUGenerator/README.md

📄 SSAU Generator

SSAU Generator — это два независимых генератора отчётных документов из обычного Markdown: DOCX-отчёт по СТО 02068410-004-2018 и PPTX-презентация по шаблону Самарского университета.

Главное — это модульность и воспроизводимая сборка: содержимое задаётся Markdown и config.yaml, а не правками кода.

---

📦 Состав

• docx/ — генератор документов DOCX по дизайну СТО 02068410-004-2018
  • Титульный лист, оглавление, таблицы, рисунки (включая PlantUML), формулы, список источников и приложения
• pptx/ — генератор презентаций PPTX по фирменному шаблону Самарского университета
  • 16:9, синий фон, задники, логотип и фирменный шрифт заданы в config.yaml
• tools/plantuml.jar — общий рендерер схем PlantUML (не хранится в git)
• content/ — проекты пользователя: content/<проект>/{docx,pptx} и общие ресурсы content/<проект>/assets/

---

🚀 Возможности

📄 Документ DOCX

• Сборка из обычного Markdown по фиксированному дизайну СТО 02068410-004-2018
• Готовый титульный лист (отдельный .docx) и оглавление (поле Word)
• Автоматическая нумерация разделов, рисунков, таблиц, формул и приложений
• Таблицы — обычные и с подписью и автономером
• Рисунки — готовые PNG и схемы PlantUML, рендеримые автоматически
• Формулы с пояснениями и нумерацией
• Ссылки на источники и перекрёстные ссылки на номера объектов
• Примечания, определения, приложения с буквенной нумерацией

📽️ Презентация PPTX

• Сборка из Markdown, по одному файлу на слайд
• Четыре типа слайдов: титульный, разделитель, контент, финальный — каждый со своим фоном
• Богатая inline-разметка: полужирный, курсив, акцент, моноширинный
• Таблицы, изображения и PlantUML, схемы-цепочки, карточки-метрики, плашки-выводы
• Диаграммы (bar, line, pie, doughnut, area, radar, scatter) из GFM-таблиц
• Заметки докладчика как сценарий выступления
• Двухколоночная вёрстка через параметр side=left|right

---

📂 Структура

ssau-generator/
├── docx/            # генератор DOCX (только код)
├── pptx/            # генератор PPTX (только код)
├── tools/           # общий plantuml.jar (не в git)
├── content/         # проекты (в git хранится только example)
│   └── example/
│       ├── assets/  # общие ресурсы проекта (для docx и pptx)
│       ├── docx/    # config.yaml + *.md
│       └── pptx/    # config.yaml + slides/
├── AGENTS.md        # инструкции по управлению проектом
└── README.md

Каждый проект — отдельная папка content/<проект>/. Готовый пример со всеми возможностями — content/example/.

---

🛠 Требования

• Node.js 18+ и зависимости, устанавливаемые командой npm install в docx/ и pptx/
• Java 11+ и файл tools/plantuml.jar — для рендеринга схем PlantUML (.puml)

---

📝 Быстрый старт

npm install --prefix docx
npm install --prefix pptx

# Документ DOCX
node docx/src/cli.js --content content/example/docx

# Презентация PPTX
node pptx/src/cli.js -c content/example/pptx/config.yaml

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

---

🎯 Использование

Новый проект

Проект создаётся командами с флагом --init — они формируют структуру и общий каталог ресурсов content/<проект>/assets/:

# только документ DOCX
node docx/src/cli.js --content content/<проект>/docx --init

# только презентация PPTX
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --init

Сборка

# Документ DOCX
node docx/src/cli.js --content content/<проект>/docx --check
node docx/src/cli.js --content content/<проект>/docx

# Презентация PPTX
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --check
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml

Результат собирается в папку проекта и называется по имени проекта: content/<проект>/<проект>.docx и content/<проект>/<проект>.pptx.

---

📚 Документация

• Управление проектом: AGENTS.md
• Формат DOCX-документа: docx/AGENTS.md
• Формат PPTX-презентации: pptx/AGENTS.md

💡 Важно: Документ и презентация используют общий каталог ресурсов content/<проект>/assets/, поэтому титульный лист, задники и изображения переиспользуются обоими генераторами.