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
317 lines
14 KiB
Markdown
317 lines
14 KiB
Markdown
# AGENTS.md — работа с документом DOCX
|
||
|
||
Генератор `docx/` собирает отчёт в формате **DOCX** из обычных **Markdown**-файлов
|
||
по фиксированному дизайну СТО 02068410-004-2018. Этот файл — инструкция агенту по
|
||
созданию и правке конкретного документа. Поведение полностью задаётся `config.yaml`
|
||
проекта, менять код генератора не нужно.
|
||
|
||
## 1. Требования
|
||
|
||
- Node.js 18+, зависимости ставятся командой `npm install` в папке `docx/`.
|
||
- Windows/macOS/Linux.
|
||
- Готовые PNG вставляются без внешних зависимостей. Для рендеринга PlantUML
|
||
(`.puml`) нужны Java 11+ и файл `plantuml.jar` (см. `plantuml` в конфиге).
|
||
|
||
## 2. Раскладка проекта
|
||
|
||
Проект лежит в `content/<проект>/docx/` рядом с `config.yaml`:
|
||
|
||
```
|
||
content/<проект>/
|
||
├── assets/ # общие ресурсы проекта (общие с pptx)
|
||
│ ├── title-page.docx # титульный лист
|
||
│ └── images/ # PNG-рисунки и исходники .puml
|
||
└── docx/
|
||
├── config.yaml # настройки документа
|
||
├── 01-introduction.md
|
||
├── 02-*.md
|
||
└── 05-bibliography.md
|
||
```
|
||
|
||
Все относительные пути в `config.yaml` считаются **от каталога самого
|
||
`config.yaml`**. Если ресурсы общие с презентацией, указывайте их через `../assets`
|
||
(например, `paths.assets: ../assets`, `document.titlePage: ../assets/title-page.docx`).
|
||
|
||
Отчёт собирается в папку проекта и называется по имени проекта:
|
||
`content/<проект>/<проект>.docx`. Значение ключа `document.output` при такой
|
||
раскладке — `../<проект>.docx`.
|
||
|
||
Структуру проекта создавайте командой `--init`: она формирует `config.yaml`,
|
||
примеры `*.md` и общий каталог `content/<проект>/assets/` (титульный лист,
|
||
изображения), который используется и генератором `pptx`.
|
||
|
||
Готовый пример со всеми возможностями — `content/example/docx/`.
|
||
|
||
## 3. Командная строка
|
||
|
||
Из корня репозитория:
|
||
|
||
```
|
||
node docx/src/cli.js [опции]
|
||
|
||
--config <путь> путь к config.yaml (по умолчанию config.yaml в текущем каталоге)
|
||
--content <dir> каталог проекта: config.yaml, *.md и assets/ (по умолчанию текущий)
|
||
--output <путь> переопределить путь выходного .docx
|
||
--check только проверить конфиг и ссылки, без записи файла
|
||
--init создать шаблон config.yaml/*.md/assets и выйти
|
||
--verbose подробный вывод
|
||
--version показать версию
|
||
--help справка
|
||
```
|
||
|
||
Типичный цикл:
|
||
|
||
```powershell
|
||
node docx/src/cli.js --content content/<проект>/docx --init # создать структуру проекта
|
||
node docx/src/cli.js --content content/<проект>/docx --check # проверить
|
||
node docx/src/cli.js --content content/<проект>/docx # собрать
|
||
```
|
||
|
||
После любого изменения исходников (`config.yaml`, `*.md`, ресурсов `assets/`)
|
||
**пересоберите документ**, чтобы результат соответствовал исходникам.
|
||
|
||
Если `config.yaml` не найден, инструмент сам создаёт шаблон (`config.yaml`,
|
||
примеры Markdown и общий `assets/`) и завершается.
|
||
|
||
## 4. Схема `config.yaml`
|
||
|
||
Любой ключ можно опустить — берётся значение по умолчанию (см.
|
||
`docx/src/config/defaults.js`).
|
||
|
||
### document
|
||
| Ключ | Тип | Смысл |
|
||
|------|-----|-------|
|
||
| `output` | string | путь выходного `.docx` (относительно `config.yaml`) |
|
||
| `titlePage` | string/null | путь к готовому `title-page.docx`; `null` — без титульника |
|
||
| `features.updateFields` | bool | обновлять поля (в т.ч. оглавление) при открытии в Word |
|
||
|
||
Титульный лист склеивается перед документом, между ним и текстом вставляется
|
||
разрыв страницы. При `--init` создаётся пример `assets/title-page.docx`.
|
||
|
||
### paths
|
||
| Ключ | Смысл |
|
||
|------|-------|
|
||
| `assets` | корень ресурсов; `file=images/x.png` в директивах ищется здесь |
|
||
|
||
### Структура и оформление
|
||
|
||
| Раздел | Назначение |
|
||
|--------|-----------|
|
||
| `page` | `width`, `height` (DXA), `margins` (twips) |
|
||
| `typography` | `font`, `sizeBody`/`sizeTable`/`sizeSmall`, `lineSpacing`, `color`, `useBold`, `allowEmphasis`, `language` |
|
||
| `headings` | интервалы/выравнивание `struct`, `section`, `subsection`, `point` |
|
||
| `captions` | префиксы и тире подписей `figure`, `table`, `tableContinue` |
|
||
| `lists` | `bulletChar`, `letterSuffix`, `numberSuffix`, `nestedLevelStep`, `forbiddenLetters` |
|
||
| `numbering` | `figures`, `tables`, `formulas`: `global` или `section` |
|
||
| `formula` | `spacingBeforeAfter`, `whereTabPosition` |
|
||
| `table` | `font`, `size`, `borderColor`, `borderSize`, `cellMargins`, `headerFill`, `cellFill` |
|
||
| `figure` | `maxWidth` (px, `null` — по ширине), `maxHeight` (px) |
|
||
| `pageNumber` | `align`, `format`, `startFrom` |
|
||
| `toc` | `enabled`, `title`, `depth` (1..3) |
|
||
| `bibliography` | `title` |
|
||
| `citation` | `bracketOpen`, `bracketClose`, `pagePrefix` |
|
||
| `appendix` | `labelPrefix`, `forbiddenLetters` |
|
||
|
||
### plantuml
|
||
|
||
| Ключ | Тип | Смысл |
|
||
|------|-----|-------|
|
||
| `enabled` | bool | включить рендеринг `.puml`; `false` — считать ошибкой |
|
||
| `java` | string | `auto` — `%JAVA_HOME%\bin\java`, иначе `java` из PATH |
|
||
| `jar` | string | путь к `plantuml.jar` (относительно `config.yaml`) |
|
||
| `format` | string | только `png` |
|
||
| `charset` | string | кодировка исходника (по умолчанию `UTF-8`) |
|
||
| `cache` | bool | не перерисовывать неизменённый исходник |
|
||
| `cacheDir` | string | каталог кэша PNG (относительно `config.yaml`) |
|
||
| `timeoutMs` | int | таймаут рендера одной диаграммы, мс |
|
||
|
||
Общий `plantuml.jar` репозитория лежит в `tools/plantuml.jar`; из проекта путь
|
||
вида `../../../tools/plantuml.jar`. Ошибки рендера (нет `jar`, нет Java,
|
||
синтаксическая ошибка) — фатальные: сборка останавливается с кодом `1`.
|
||
|
||
### sections — структура документа
|
||
|
||
Упорядоченный список частей:
|
||
|
||
```yaml
|
||
sections:
|
||
- { type: toc } # поле оглавления
|
||
- { file: 01-introduction.md, type: structural, title: Введение }
|
||
- { file: 02-main.md, type: numbered } # # = 1, ## = 1.1, ### = 1.1.1
|
||
- { file: 04-conclusion.md, type: structural, title: Заключение }
|
||
- { file: 05-bibliography.md, type: bibliography }
|
||
- { file: 06-appendix-a.md, type: appendix, letter: А, title: Приложение }
|
||
```
|
||
|
||
| type | Поведение |
|
||
|------|-----------|
|
||
| `toc` | вставляет оглавление (не требует `file`) |
|
||
| `structural` | ненумерованный раздел (Введение/Заключение): заголовок = `title`, ЗАГЛАВНЫМИ, по центру, с новой страницы |
|
||
| `numbered` | нумеруемый раздел; `#` = раздел, `##`/`###` = подраздел/пункт |
|
||
| `bibliography` | список источников; нумеруется автоматически |
|
||
| `appendix` | приложение: заголовок «ПРИЛОЖЕНИЕ <letter>» + `title`, буквенный префикс у рисунков/таблиц |
|
||
|
||
## 5. Формат контента
|
||
|
||
### Заголовки
|
||
|
||
В файле `type: numbered`:
|
||
|
||
```md
|
||
# НАЗВАНИЕ РАЗДЕЛА -> 1 НАЗВАНИЕ РАЗДЕЛА (с новой страницы)
|
||
## Подраздел -> 1.1 Подраздел
|
||
### Пункт -> 1.1.1 Пункт
|
||
```
|
||
|
||
Номера подставляются автоматически (Word-numbering). В `structural`/`appendix`
|
||
заголовок берётся из `title`, а заголовки внутри файла рендерятся без номера.
|
||
|
||
### Абзацы и списки
|
||
|
||
Обычные абзацы и списки Markdown. Пример:
|
||
|
||
```md
|
||
- первый пункт;
|
||
- второй пункт:
|
||
1. вложенный пункт (выведется как «а) вложенный пункт»);
|
||
2. ещё один.
|
||
```
|
||
|
||
Маркер вложенности выбирается автоматически: тире → `а)` → `1)`. Полужирный и
|
||
курсив по умолчанию игнорируются (СТО).
|
||
|
||
### Таблицы
|
||
|
||
- Обычная GFM-таблица без директивы — таблица **без подписи и номера**.
|
||
- С подписью и автономером — директива `::: table`:
|
||
|
||
```md
|
||
::: table "Название таблицы" id=params note="примечание"
|
||
| Параметр | Значение |
|
||
|---|---|
|
||
| A | 1 |
|
||
| B | 2 |
|
||
:::
|
||
```
|
||
|
||
### Рисунки
|
||
|
||
```md
|
||
::: figure "Название рисунка" id=arch file=images/arch.png
|
||
а) первый поясняемый элемент;
|
||
б) второй поясняемый элемент.
|
||
:::
|
||
```
|
||
|
||
`file` — относительно `paths.assets`. Если файла нет — предупреждение, подпись
|
||
всё равно выводится. Подпись ставится под рисунком по центру:
|
||
`Рисунок N — Наименование`. Если пояснять нечего, тело директивы оставляют
|
||
пустым:
|
||
|
||
```md
|
||
::: figure "Общая схема системы" id=common file=images/common.png
|
||
:::
|
||
```
|
||
|
||
**PlantUML.** Если `file` оканчивается на `.puml` (`.plantuml`, `.pu`, `.iuml`),
|
||
файл рендерится в PNG через `plantuml.jar` и вставляется как обычный рисунок:
|
||
|
||
```md
|
||
::: figure "Диаграмма последовательности" id=seq file=images/seq.puml
|
||
а) запрос клиента;
|
||
б) ответ сервера.
|
||
:::
|
||
```
|
||
|
||
Ошибка рендера фатальна, `--check` тоже рендерит `.puml`.
|
||
|
||
В приложениях номер рисунка получает префикс буквы: `Рисунок А.1 — Наименование`.
|
||
|
||
### Формулы
|
||
|
||
```md
|
||
::: formula id=line
|
||
y = a*x + b
|
||
:::
|
||
|
||
::: where
|
||
y — результат;
|
||
x — аргумент;
|
||
a — коэффициент.
|
||
:::
|
||
```
|
||
|
||
Поддерживается простой синтаксис: `^` (степень), `_` (индекс), `/` (дробь). Номер
|
||
формулы ставится автоматически справа.
|
||
|
||
### Примечания и термины
|
||
|
||
```md
|
||
::: note
|
||
Текст примечания.
|
||
:::
|
||
|
||
::: notes
|
||
- первое примечание;
|
||
- второе примечание.
|
||
:::
|
||
|
||
::: definitions
|
||
Термин — определение;
|
||
Ещё термин — определение.
|
||
:::
|
||
```
|
||
|
||
### Разрыв страницы
|
||
|
||
```md
|
||
::: pagebreak
|
||
:::
|
||
```
|
||
|
||
Тематический разрыв `---` также трактуется как разрыв страницы.
|
||
|
||
### Ссылки на источники
|
||
|
||
`[@1]` — ссылка на 1-й источник, `[@1, с. 96]` — с номером страницы. Список
|
||
источников — Markdown-список в файле `type: bibliography`; порядок строк = номера.
|
||
Ссылка вне диапазона — ошибка в `--check`.
|
||
|
||
### Перекрёстные ссылки
|
||
|
||
`@fig:id`, `@tbl:id`, `@eq:id` подставляют актуальный номер рисунка/таблицы/
|
||
формулы (например `2`, `1.1`, `А.1`). `id` задаётся в директиве.
|
||
|
||
### Блоки кода
|
||
|
||
Fenced-блоки ``` игнорируются с предупреждением (функция листингов удалена).
|
||
|
||
## 6. Проверка и ошибки
|
||
|
||
`--check` проверяет:
|
||
|
||
- корректность `config.yaml` (типы, существование файлов, буквы приложений);
|
||
- наличие всех `sections[].file`;
|
||
- существование меток в `@fig/@tbl/@eq`;
|
||
- диапазон ссылок `[@n]`;
|
||
- рендеринг всех `::: figure ... file=*.puml`.
|
||
|
||
Ошибки печатаются списком и возвращают код выхода `1`. Предупреждения (например,
|
||
отсутствующий PNG) не останавливают сборку; ошибки PlantUML — фатальные.
|
||
|
||
## 7. Подготовка диаграмм
|
||
|
||
Готовые PNG кладутся в общий каталог ресурсов (`content/<проект>/assets/images/`).
|
||
Исходники PlantUML (`.puml`) кладутся туда же и указываются в
|
||
`::: figure ... file=images/<имя>.puml`. Диаграммы других форматов (Mermaid,
|
||
draw.io) готовятся внешними средствами и вставляются как PNG.
|
||
|
||
## 8. Замечания по дизайну
|
||
|
||
- Дизайн фиксирован под СТО 02068410-004-2018; меняются только параметры из
|
||
`config.yaml`.
|
||
- Полужирный и курсив по умолчанию отключены (`typography.useBold`,
|
||
`allowEmphasis`).
|
||
- Оглавление — поле Word; при открытии нажмите «Обновить поле» либо включите
|
||
`document.features.updateFields`.
|