Igor20264md2gost (ТЗ МИРЭА)
Конвертер 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 / IDEF0 / DFD / схемы | %id Подпись + uml` / uml-c4 / ````mermaid / idef0` / dfd→ Рисунок;+listing— ещё и Листинг. Схемы вmd2gost.schemes.json` |
| Формула | %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). Таблицы с вертикальным merge (^): Word не умеет Split при vMerge — merge временно снимается, после разреза восстанавливается в обоих фрагментах |
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. Mermaid — mermaid` / mmd: системный браузер → Playwright Chromium → QuickJS (mermaidx) → Kroki (свой --kroki-url или kroki.io). **IDEF0** — ````idef0: локальный Pillow (рамка NIST, стрелки ICOM). DFD — ````dfd: [data-flow-diagram](https://github.com/pbauermeister/dfd) → вшитый/системный Graphviz или Kroki (scripts/fetch_graphviz.py`, GUI «Скачать Graphviz»).
Обычному пользователю jar/Kroki указывать не нужно. Порядок для UML:
- Вшитый / скачанный
plantuml.jar+ Java (exe кладёт jar внутрь; иначе качаем в%LOCALAPPDATA%\md2gost\) - Локальный Kroki (
KROKI_URL/--kroki-url, по умолчаниюhttp://localhost:8000) - Интернет
https://kroki.ioпри--diagram-fallback remote(по умолчанию)
Mermaid:
- Системный Chrome / Edge (Playwright channel, ничего не тащим)
- Playwright Chromium в
%LOCALAPPDATA%\md2gost\ms-playwright— GUI «Скачать headless Chromium» илиmd2gost --install-chromium - QuickJS + mermaid.js (
mermaidx) — офлайн без браузера - Локальный Kroki →
https://kroki.ioпри--diagram-fallback remote
DFD (````dfd`):
- Пакет
data-flow-diagram(зависимость md2gost) → DOT - Graphviz: вшитый
md2gost/vendor/graphviz(сборка exe /scripts/fetch_graphviz.py) →%LOCALAPPDATA%\md2gost\graphviz(GUI «Скачать Graphviz») →PATH - Локальный Kroki →
https://kroki.ioпри--diagram-fallback remote
Формат в Word: --diagram-format png (по умолчанию; PlantUML и локальный Mermaid с --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 scripts/fetch_graphviz.py
python scripts/fetch_mermaid.py
python -m md2gost --install-chromium
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.