md_to_gost/md2gost

md2gost (ТЗ МИРЭА)

Конвертер Markdown → DOCX по методическим указаниям РТУ МИРЭА (ГОСТ 7.32-2017) на базе md2gost.

Полная документация: docs/ (быстрый старт, синтаксис, схемы, типы, CLI/GUI, промпты).

Установка

poetry install
# или
pip install -e .

GUI

Без файла или с --gui открывается окно: перетащите .md, выберите параметры, нажмите «Конвертировать». CLI при этом тот же (python -m md2gost файл.md …).

python -m md2gost
python -m md2gost --gui
python -m md2gost --gui report.md --type PIS_custom
md2gost-gui

На Windows файл можно бросить из Проводника в верхнюю область окна. Клик по области — выбор через диалог. Все флаги CLI есть в форме (тип, нумерация, TOC, тире, --- → разрыв страницы, титул/задание, диаграммы, проверка ТЗ).

Вкладки Инструкция и Промпт для ИИ — справка и копирование системного промпта (с опциональным дописыванием UML-схем) в буфер.

Сборка exe (Windows)

Двойной клик по build-exe.bat в корне репозитория (нужен Python 3.10+ в PATH). Результат: dist\md2gost.exe.

build-exe.bat
build-exe.bat nopause

Двойной клик по exe — GUI. CLI: md2gost.exe report.md -o report.docx --type coursework.

CLI

python -m md2gost report.md -o report.docx --type coursework --check

FODT (LibreOffice, без Word): python -m md2fodt report.md -o report.fodt — см. md2fodt/.

Типы: coursework | practice | vkr | PIS_custom | APID_coursework.

Тип	Когда	Отличия
coursework / practice / vkr	ТЗ МИРЭА / ГОСТ 7.32	H1 слева с отступом; нумерация объектов 1.1, 2.1; введение/заключение/список
PIS_custom	Итоговый отчёт по практическим работам	H1 по центру ПРОПИСНЫМИ; H2 с абзацным отступом; нумерация сквозная (1, 2, 3); H1 = «Практическая работа №N. …»
APID_coursework	КР «Архитектура приложений и данных»	Стили как у coursework; источники 7–20; проверка глав «Теоретические…» / «Прикладные…» и пунктов 2.1–2.4

python -m md2gost report.md -o report.docx --type PIS_custom --check
# Титул: «Отчёт по практическим работам …» — отдельный DOCX:
python -m md2gost report.md -o report.docx --type PIS_custom --title title.docx
# Курсовая АПИД (источники 7–20, проверка пунктов 2.1–2.4):
python -m md2gost report.md -o report.docx --type APID_coursework --check --title title.docx --assignment assignment.docx

Пример: examples/pis_custom.md.

Нумерация заголовков (--heading-numbering)

Режим	Когда	Поведение
manual (по умолчанию)	В md уже есть # 1 …, ## 1.1 …	Цифры остаются из markdown; автонумерация Word отключена (нет двойных «1 1 …»)
auto	В md заголовки без цифр: # Анализ…	Нумерацию ставит Word; ведущие цифры в тексте md, если были, снимаются

Содержание (--toc)

Режим	Поведение
native (по умолчанию)	Встроенное поле Word TOC. При открытии Word предложит обновить поле (номера страниц и ссылки).
manual	Содержание собирает md2gost сам (номера из layout-трекера), без поля Word.

python -m md2gost report.md -o report.docx --toc native
python -m md2gost report.md -o report.docx --toc manual

Тире (--emdash-to-hyphen / --no-emdash-to-hyphen)

По умолчанию типографское «—» сохраняется (как в методичке: тире с пробелами, дефис в диапазонах).
Заменить «—» на «-»: --emdash-to-hyphen.

Разрыв страницы (--- / --hr-pagebreak)

Строка --- (также ***, ___) на отдельной строке по умолчанию игнорируется. Разрыв страницы: --hr-pagebreak или галочка в GUI.

Синтаксис (кратко)

Элемент	Markdown
Спецраздел	# *ВВЕДЕНИЕ
Содержание	# *СОДЕРЖАНИЕ + [TOC]
Рисунок	 + @Рисунок:id
Таблица	%id Подпись перед таблицей + @Таблица:id
Склеивание ячеек	^ — rowspan (ячейка сверху), > — colspan (ячейка слева)
Листинг	%id Подпись перед code fence
Диаграмма UML / Mermaid / схемы	%id Подпись + uml` / uml-c4 / ````bpmn / ````mermaid→ Рисунок;+listing— ещё и Листинг. Схемы вmd2gost.schemes.json`. IDEF0 нет
Формула	%eq1 + $$…$$ + @Формула:eq1 (номер только при ссылке)
Источник	[1] в тексте; [1]: … в списке
Разрыв страницы	--- на отдельной строке + --hr-pagebreak (по умолчанию --- игнорируется)

Таблицы со склеиванием

%req Требования к системе

| Категория | Описание |
|-----------|----------|
| Производительность | Требование 1 |
| ^ | Требование 2 |
| Масштабируемость | Требование 3 |
| ^ | Требование 4 |

Горизонтально: | широкий текст | > | другая | — первая ячейка на 2 столбца.

При разрыве таблицы на страницах merge не переносится через границу фрагмента.

Продолжение таблицы (--table-continuation)

Важно: ни DOCX, ни ODT не умеют сами вставлять текст «Продолжение Таблицы N» только на второй и следующих страницах. В Word есть лишь повтор шапки (tblHeader). Разные шапки «первый раз / продолжение» есть в LaTeX (longtable), не в Office.

Наша оценка высоты строк ≠ вёрстка Word → если резать таблицу в скрипте, получается mid-page «Продолжение…» (как было на 2.4). По умолчанию режим word: после save Word COM режет по реальной пагинации. Без Word — укажите off или поставьте Word + pywin32.

Режим	Поведение
word (по умолчанию)	Как off при рендере; после save Word COM: Split + «Продолжение Таблицы N». Нужны Windows, Word, pywin32. Шапка на продолжении не повторяется (вкл: --table-repeat-header)
off / soft	Одна таблица Word; перенос строк делает Word. Без автоподписи. Первая строка — повторяющаяся шапка (tblHeader). «Продолжение…» — вручную в markdown, если нужно
legacy	Режем по нашей оценке высоты + «Продолжение…» с page_break_before (могут быть дыры)
caption	Режем по оценке + явный PageBreak + «Продолжение…» (то же ограничение точности)

python -m md2gost report.md -o report.docx --table-continuation word
python -m md2gost report.md -o report.docx --table-continuation off
python -m md2gost report.md -o report.docx --table-continuation caption

Продолжение листинга (--listing-continuation)

Те же режимы, что у таблиц. По умолчанию word.

Режим	Поведение
word (по умолчанию)	После save Word COM + «Продолжение Листинга N» (Windows + Word + pywin32)
off / soft	Один блок кода; пагинацию делает Word. «Продолжение…» — вручную в markdown, если нужно
legacy	Режем по оценке высоты + «Продолжение Листинга N» с page_break_before
caption	Режем по оценке + явный PageBreak + «Продолжение Листинга N»

python -m md2gost report.md -o report.docx --listing-continuation word
python -m md2gost report.md -o report.docx --listing-continuation off
python -m md2gost report.md -o report.docx --listing-continuation caption

Диаграммы

В отчёте пишите так (пример в 4 обратных кавычках, чтобы вложенный ```uml не ломал разметку):

%usecase1 Диаграмма прецедентов +listing

```uml
@startuml
actor Student
Student --> (Login)
@enduml
```

Широкая схема на альбомной странице — флаг +landscape в той же строке %:

%arch1 Архитектура +landscape

Person(user, "Студент")
System(app, "Портал")

%arch1 Архитектура +landscape

```uml-c4
Person(user, "Студент")
System(app, "Портал")
```

Схемы (c4, usecase, свои): при первом запуске рядом с приложением создаётся md2gost.schemes.json. В markdown — оградка uml-<id> или короткое <id>:

%arch C4

```uml-c4
Person(user, "Студент")
System(app, "Портал")
Rel(user, app, "логин")
```

URL в includes схемы скачиваются в кэш (md2gost.include-cache.json + папка include-cache/). CLI: --schemes path.json. BPMN 2.0 — оградка bpmn` / uml-bpmn(макросыStart, UserTask, XOR, Flow, Pool…; библиотека diagrams/BPMN.puml). **Mermaid** — ````mermaid / ````mmdчерез тот же Kroki (свой--kroki-url` или kroki.io); jar не используется. IDEF0 конвертер не рисует — вставляйте готовый PNG.

StartMessage(s, "заявка")
UserTask(t, "Проверить")
XOR(gw, "ок?")
End(e_ok)
End(e_no)
Flow(s, t)
Flow(t, gw)
CondFlow(gw, e_ok, "да")
DefaultFlow(gw, e_no)

%bpmn1 Процесс заявки

```bpmn
StartMessage(s, "заявка")
UserTask(t, "Проверить")
XOR(gw, "ок?")
End(e_ok)
End(e_no)
Flow(s, t)
Flow(t, gw)
CondFlow(gw, e_ok, "да")
DefaultFlow(gw, e_no)
```

Обычному пользователю jar/Kroki указывать не нужно. Порядок для UML:

1. Вшитый / скачанный plantuml.jar + Java (exe кладёт jar внутрь; иначе качаем в %LOCALAPPDATA%\md2gost\)
2. Локальный Kroki (KROKI_URL / --kroki-url, по умолчанию http://localhost:8000)
3. Интернет https://kroki.io при --diagram-fallback remote (по умолчанию)

Mermaid всегда идёт через Kroki (шаги 2–3).

Формат в Word: --diagram-format png (по умолчанию; PlantUML рендерится с --diagram-scale, по умолчанию 2 — только качество, размер на странице как при 1) или svg — вектор через svgBlip + PNG-запасной (Word 2016+; LibreOffice покажет растр).

Широкие схемы/таблицы: в подписи флаг +landscape — отдельная альбомная A4-страница, затем снова книжная.

Свой jar — только если нужен другой файл: --plantuml-jar или поле на вкладке «Диаграммы».

Кэш: {каталог_md}/.md2gost-cache/ (*.png, при svg ещё *.svg).

python scripts/fetch_plantuml.py
python -m md2gost report.md -o report.docx --diagram-fallback local
python -m md2gost report.md -o report.docx --diagram-format svg

Подробности и ИИ-промпт: prompts/.

PDF через LaTeX (XeLaTeX, шаблон МИРЭА): md2latex/README.md.

Проверки

--check печатает замечания по структуре, «рис.», ссылкам во введении, числу/возрасту источников, приложениям и т.д. --strict завершает процесс с кодом 1 при ошибках.

--check-pages — пост-проверка полупустых страниц через Microsoft Word (Windows + Word + pip install pywin32). Все находки помечены как эвристика и могут быть ложными; не влияют на --strict. Можно вызвать для готового файла: python -m md2gost report.docx --check-pages. Макрос Word: scripts/check_page_fill.bas.