Igor20264
1a5b35eb54
Python application / build (push) Has been cancelled
- add Local Render Mermaid - add page-starе для указания смещения страниц - add Гиперссылки в документе на списки литературы
127 lines
5.4 KiB
Markdown
127 lines
5.4 KiB
Markdown
# Схемы и диаграммы
|
||
|
||
В отчёте блок кода с языком диаграммы превращается в **Рисунок** (PNG или SVG). PNG руками экспортировать не нужно: md2gost вызывает PlantUML (jar / Kroki) или локальный Mermaid (браузер / QuickJS), иначе Kroki.
|
||
|
||
## Синтаксис в markdown
|
||
|
||
````markdown
|
||
%usecase1 Диаграмма прецедентов +listing
|
||
|
||
```uml
|
||
@startuml
|
||
actor Student
|
||
Student --> (Login)
|
||
@enduml
|
||
```
|
||
````
|
||
|
||
Широкая схема:
|
||
|
||
````markdown
|
||
%arch1 Архитектура +landscape
|
||
|
||
```uml-c4
|
||
Person(user, "Студент")
|
||
System(app, "Портал")
|
||
Rel(user, app, "логин")
|
||
```
|
||
````
|
||
|
||
| Оградка | Что происходит |
|
||
|---------|----------------|
|
||
| `` ```uml `` / `` ```plantuml `` | Сырой PlantUML (`@startuml`…`@enduml`) |
|
||
| `` ```uml-<id> `` / `` ```<id> `` | Схема из `md2gost.schemes.json` (обёртка и `!include` добавляются сами) |
|
||
| `` ```mermaid `` / `` ```mmd `` | Mermaid: браузер / QuickJS / Kroki |
|
||
| `` ```bpmn `` / `` ```uml-bpmn `` | BPMN 2.0 (макросы библиотеки md2gost) |
|
||
|
||
**IDEF0 / DFD** конвертер не рисует — вставляйте готовый PNG как обычный Рисунок.
|
||
|
||
## Встроенные схемы
|
||
|
||
Файл шаблона: [`md2gost/diagrams/schemes.json`](../md2gost/diagrams/schemes.json). При первом запуске копируется в `md2gost.schemes.json` рядом с приложением (существующий файл не перезаписывается).
|
||
|
||
| id | Название | Оградка |
|
||
|----|----------|---------|
|
||
| `c4` | C4 Container | `` ```uml-c4 `` / `` ```c4 `` |
|
||
| `c4context` | C4 Context | `` ```uml-c4context `` |
|
||
| `c4component` | C4 Component | `` ```uml-c4component `` |
|
||
| `usecase` | Прецеденты | `` ```uml-usecase `` / `` ```usecase `` |
|
||
| `bpmn` | BPMN 2.0 | `` ```bpmn `` / `` ```uml-bpmn `` |
|
||
|
||
Для схем в теле пишите **только макросы** (Person, Start, XOR, …) — без `@startuml` и без `!include`, если схема сама их добавляет.
|
||
|
||
### C4 (пример макросов)
|
||
|
||
`Person`, `System`, `System_Ext`, `Container`, `ContainerDb`, `Rel` / `Rel_R`…
|
||
|
||
### Use Case
|
||
|
||
`actor`, `usecase`, связи `-->`, `<<include>>`, `<<extend>>`.
|
||
|
||
### BPMN
|
||
|
||
`Pool` / `Lane`, `Start` / `StartMessage` / `End`, `UserTask` / `ServiceTask`, `XOR` / `AND` / `OR`, `Flow` / `CondFlow` / `DefaultFlow` / `MessageFlow`, …
|
||
|
||
Sequence Flow только внутри пула; между пулами — `MessageFlow`.
|
||
|
||
Полные шпаргалки — поля `docs` и `ai-prompt` в JSON; в GUI: **Шаблоны UML** и кнопки схем в **Справка → Промпт для ИИ**.
|
||
|
||
## Файл схем: поля
|
||
|
||
```json
|
||
{
|
||
"c4": {
|
||
"title": "C4 Container",
|
||
"docs": "…макросы…",
|
||
"ai-prompt": "…инструкция для ИИ…",
|
||
"includes": ["https://…/C4_Container.puml"],
|
||
"prefix": "@startuml\n",
|
||
"postfix": "\nLAYOUT_WITH_LEGEND()\n@enduml"
|
||
}
|
||
}
|
||
```
|
||
|
||
| Поле | Назначение |
|
||
|------|------------|
|
||
| `title` | Подпись в GUI |
|
||
| `docs` | Шпаргалка макросов |
|
||
| `ai-prompt` | Фрагмент для промпта ИИ |
|
||
| `includes` | Локальные `.puml` или URL |
|
||
| `prefix` / `postfix` | Обёртка вокруг тела |
|
||
| `theme` | опционально `!theme …` |
|
||
|
||
id схемы: латиница, цифры, `_`; начинается с буквы.
|
||
|
||
## Слои загрузки (позже побеждает)
|
||
|
||
1. Встроенный шаблон `md2gost/diagrams/schemes.json`
|
||
2. Пользовательский файл рядом с приложением (`md2gost.schemes.json`)
|
||
3. `md2gost.schemes.json` рядом с `.md`
|
||
4. Явный путь `--schemes path.json`
|
||
|
||
## Рендер
|
||
|
||
**UML / схемы:**
|
||
|
||
1. Java + `plantuml.jar` (вшитый / `%LOCALAPPDATA%\md2gost\` / `--plantuml-jar`)
|
||
2. Локальный Kroki (`KROKI_URL` / `--kroki-url`, по умолчанию `http://localhost:8000`)
|
||
3. `https://kroki.io` при `--diagram-fallback remote` (по умолчанию)
|
||
|
||
**Mermaid:**
|
||
|
||
1. Системный Chrome / Edge (через Playwright, ничего не качаем)
|
||
2. Playwright Chromium в `%LOCALAPPDATA%\md2gost\ms-playwright` — кнопка «Скачать headless Chromium» или `md2gost --install-chromium`
|
||
3. QuickJS + mermaid.js (`mermaidx`) — офлайн без браузера
|
||
4. Локальный Kroki → `https://kroki.io` (если `--diagram-fallback remote`)
|
||
|
||
Формат: `--diagram-format png` (по умолчанию) или `svg`. Масштаб растра PlantUML / локального Mermaid: `--diagram-scale` (по умолчанию 2 — качество, размер на странице как при 1).
|
||
|
||
Кэш картинок: `{каталог_md}/.md2gost-cache/`.
|
||
Кэш includes: `md2gost.include-cache.json` + папка `include-cache/` (сброс в GUI: Настройки → Диаграммы / Шаблоны UML).
|
||
|
||
## Свои схемы
|
||
|
||
1. Меню **Шаблоны UML** — добавить / править / сохранить.
|
||
2. Или править `md2gost.schemes.json` вручную («Открыть JSON»).
|
||
3. CLI: `--schemes путь.json`.
|