mirror of
https://github.com/StepanovPlaton/SSAUGenerator.git
synced 2026-10-31 10:18:29 +04:00
133 lines
7.7 KiB
Markdown
133 lines
7.7 KiB
Markdown
# 📄 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
|
||
- **`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
|
||
├── content/ # проекты (в git хранится только example)
|
||
│ └── example/
|
||
│ ├── assets/ # общие ресурсы проекта (для docx и pptx)
|
||
│ ├── docx/ # config.yaml + *.md
|
||
│ └── pptx/ # config.yaml + slides/
|
||
├── AGENTS.md # инструкции по управлению проектом
|
||
└── README.md
|
||
```
|
||
|
||
> Каждый проект — отдельная папка `content/<проект>/`. Готовый пример со всеми возможностями — [`content/example/`](content/example/).
|
||
|
||
---
|
||
|
||
## 🛠 Требования
|
||
|
||
- **Node.js 18+** и зависимости, устанавливаемые командой `npm install` в `docx/` и `pptx/`
|
||
- **Java 11+** и файл `tools/plantuml.jar` — для рендеринга схем PlantUML (`.puml`)
|
||
|
||
---
|
||
|
||
## 📝 Быстрый старт
|
||
|
||
```powershell
|
||
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/`](content/example/).
|
||
|
||
---
|
||
|
||
## 🎯 Использование
|
||
|
||
### Новый проект
|
||
|
||
Проект создаётся командами с флагом `--init` — они формируют структуру и общий каталог ресурсов `content/<проект>/assets/`:
|
||
|
||
```powershell
|
||
# только документ DOCX
|
||
node docx/src/cli.js --content content/<проект>/docx --init
|
||
|
||
# только презентация PPTX
|
||
node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --init
|
||
```
|
||
|
||
`--init` создаёт в общем каталоге ресурсов `content/<проект>/assets/` титульный лист `title-page.docx` (образец), который затем используется при сборке.
|
||
|
||
### Сборка
|
||
|
||
```powershell
|
||
# Документ 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`.
|
||
|
||
### 📄 Титульный лист и оглавление
|
||
|
||
- **Титульный лист** берётся из файла `document.titlePage` (по умолчанию `content/<проект>/assets/title-page.docx`) и **приклеивается в начало** сгенерированного документа. Образец, созданный при `--init`, содержит условные данные: **отредактируйте его вручную** под свой проект (ФИО, группа, тема, преподаватель и т. п.) — при повторной сборке используется именно этот файл.
|
||
- **Оглавление** вставляется как поле Word и при генерации остаётся пустым. После сборки откройте документ в Word и **нажмите «Обновить поле» / «Обновить оглавление»** — оно заполнится автоматически на основе фактических заголовков. Либо включите `document.features.updateFields: true`, и Word обновит поле при открытии.
|
||
|
||
---
|
||
|
||
## 📚 Документация
|
||
|
||
- Управление проектом: [AGENTS.md](AGENTS.md)
|
||
- Формат DOCX-документа: [docx/AGENTS.md](docx/AGENTS.md)
|
||
- Формат PPTX-презентации: [pptx/AGENTS.md](pptx/AGENTS.md)
|
||
|
||
> 💡 **Важно:** Документ и презентация используют общий каталог ресурсов `content/<проект>/assets/`, поэтому титульный лист, задники и изображения переиспользуются обоими генераторами.
|