16 KiB
Запуск, профили и настройки md2gost
Справочник по CLI, типам документов, конфигурационным файлам и оформлению. Движок один: интерфейс собирает те же параметры, что и аргументы командной строки.
1. Основные команды
python -m md2gost # окно интерфейса
python -m md2gost report.md -o report.docx --type coursework --check
python -m md2gost report.md --check-only --type vkr --strict
python -m md2gost report.docx -o report.md # импорт Word → Markdown
python -m md2gost report.docx --check-pages # проверка вёрстки готового DOCX
python -m word2md report.docx -o report.md # то же импортом напрямую
python -m md2fodt report.md -o report.fodt # экспорт в формат LibreOffice
md2gost-gui # окно интерфейса, точка входа
Без имени файла или с ключом --gui открывается окно. Windows-сборка: build-exe.bat даёт dist\md2gost.exe, двойной клик открывает окно, аргументы работают так же.
2. Типы документов --type
| Тип | Назначение | Нумерация объектов | Источники | Стиль |
|---|---|---|---|---|
practice (по умолчанию) |
отчёт по практике | по разделам: 1.1, 2.3 | 5–7, не старше 5 лет | МИРЭА |
coursework |
курсовая работа | по разделам | 5–7, не старше 5 лет | МИРЭА |
vkr |
выпускная квалификационная работа | по разделам | не менее 10 в каждом подразделе списка | МИРЭА |
APID_coursework |
курсовая «Архитектура приложений и данных» | по разделам | 7–20, не старше 5 лет | МИРЭА |
PIS_custom |
итоговый отчёт по практическим работам | сквозная: 1, 2, 3 | не требуются | ПИС |
Что меняет профиль:
| Свойство | МИРЭА-профили | PIS_custom |
|---|---|---|
| H1 | 18 пт, ПРОПИСНЫЕ, слева (СОДЕРЖАНИЕ и СПИСОК — по центру) | 14 пт, ПРОПИСНЫЕ, по центру |
| H2 / H3 | 16 пт / 14 пт | 14 пт, по ширине, отступ 1,25 см |
| Введение и заключение | обязательны | не требуются |
| Список источников | обязателен | не требуется |
| Особая структура | у vkr — приложение «Графический материал»; у APID_coursework — фиксированные заголовки разделов |
H1 вида «Практическая работа №N. …» |
Общее оформление обоих пресетов: Times New Roman 14, интервал 1,5, поля 30/10/20/20 мм, абзацный отступ 1,25 см, выравнивание по ширине, подпись рисунка под ним, надписи таблицы и листинга сверху.
3. Все ключи командной строки
Ввод и вывод
| Ключ | По умолчанию | Смысл |
|---|---|---|
filename |
— | путь к .md (сборка DOCX) или .docx (импорт в Markdown) |
-o, --output |
рядом с исходником | путь результата |
-t, --template |
встроенный Template.docx |
свой шаблон DOCX |
--gui |
— | открыть окно, можно сразу с файлом |
--type |
practice |
тип документа |
Структура и разметка
| Ключ | По умолчанию | Смысл |
|---|---|---|
--heading-numbering {auto,manual} |
manual |
manual — цифры из markdown, автонумерация Word отключена; auto — нумерует Word, цифры из заголовков снимаются |
--toc {manual,native} |
native |
native — поле Word TOC (обновить при открытии); manual — md2gost собирает содержание с номерами страниц |
--emdash-to-hyphen |
выкл. | заменить все «—» на «-» |
--hr-pagebreak |
выкл. | строки ---, ***, ___ дают разрыв страницы (иначе игнорируются) |
--page-start N |
сквозная нумерация | начальный номер страницы в колонтитуле тела |
Титул, задание, метаданные
| Ключ | По умолчанию | Смысл |
|---|---|---|
--title |
— | готовый DOCX титульного листа; отключает автогенерацию |
--auto-title |
выкл. | собрать титул из info_conv.yaml и блока ```title |
--assignment |
— | DOCX бланка задания |
--student, --group |
из md2gost.user.json |
ФИО и группа для автотитула |
--doc-author-from {os,student,custom} |
os |
источник автора в свойствах DOCX |
--doc-author, --doc-last-modified-by, --doc-title, --doc-subject, --doc-keywords, --doc-comments, --doc-category |
— | поля свойств DOCX; пустое --doc-comments убирает штамп md2gost |
Проверка
| Ключ | Смысл |
|---|---|
--check |
проверить ТЗ и напечатать отчёт |
--check-only |
только проверка, без сборки |
--strict |
код выхода 1 при ошибках, документ не собирается |
--check-pages |
эвристическая проверка полупустых страниц через Microsoft Word (нужны Windows, Word, pywin32) |
Полный каталог замечаний — в checker.md.
Таблицы и листинги через границу страницы
| Ключ | По умолчанию | Значения |
|---|---|---|
--table-continuation |
word |
word — после сохранения Word COM режет по реальной пагинации и подписывает «Продолжение Таблицы N»; off и soft — одна таблица без автоподписи; legacy и caption — резать по оценке высоты (возможны артефакты) |
--listing-continuation |
word |
те же значения для листингов |
--table-repeat-header |
выкл. | повторять шапку таблицы на каждом фрагменте после разрыва |
Режим word требует Windows, установленный Microsoft Word и пакет pywin32. Без Word — --table-continuation off.
Диаграммы
| Ключ | По умолчанию | Смысл |
|---|---|---|
--plantuml-jar |
вшитый, иначе PLANTUML_JAR |
путь к plantuml.jar |
--kroki-url |
KROKI_URL, иначе http://localhost:8000 |
локальный Kroki |
--diagram-fallback {local,remote,off} |
remote |
что делать при недоступности локального рендера: remote — обратиться к kroki.io; local — ошибка; off — не рисовать |
--diagram-format {png,svg} |
png |
формат вставки; svg даёт вектор с PNG-запасным (Word 2016+) |
--diagram-scale |
2 |
масштаб растра PlantUML и локального Mermaid; размер на странице как при 1 |
--schemes |
рядом с приложением или с .md |
путь к md2gost.schemes.json |
--install-chromium |
— | скачать headless Chromium для Mermaid и выйти |
Прочее
| Ключ | По умолчанию | Смысл |
|---|---|---|
--styles |
пресет типа | путь к md2gost.styles.json |
--syntax-highlighting |
выкл. | подсветка синтаксиса в листингах |
--debug |
выкл. | отладочные данные в документе |
4. Импорт Word → Markdown
python -m word2md report.docx -o report.md
| Ключ | Смысл |
|---|---|
-o, --output |
путь к .md, по умолчанию рядом с DOCX |
--media-dir |
каталог картинок, по умолчанию <имя>_media |
--keep-toc-pages |
сохранить строки содержания Word (иначе остаётся только [TOC]) |
--pagebreaks |
писать --- на разрывах страниц |
Что распознаётся: заголовки и спецразделы, содержание, подписи «Рисунок N — …» / «Таблица N» / «Листинг N» (включая склейку «Продолжение…»), таблицы с объединением в ^ и >, листинги, формулы OMML в $$…$$, библиография [n]: …, ссылки [n], часть перекрёстных ссылок восстанавливается как @Рисунок:fig1_1.
Что теряется: исходники PlantUML и Mermaid (остаются только картинки), язык оградки листингов, осмысленные id меток, надписи и SmartArt, сноски, плавающие рисунки. Титул и бланк задания до первого заголовка пропускаются, колонтитулы не импортируются.
После импорта результат имеет смысл довести промптом ai/prompts/from-word.md и проверить --check.
5. Экспорт в FODT
python -m md2fodt report.md -o report.fodt
Ключ --emdash-to-hyphen работает так же. PDF через LaTeX — каталог md2latex/.
6. Конфигурационные файлы
| Файл | Где лежит | Назначение |
|---|---|---|
md2gost.user.json |
рядом с приложением | ФИО, группа, блок metadata со свойствами DOCX |
md2gost.schemes.json |
рядом с приложением, рядом с .md, либо путь в --schemes |
схемы диаграмм: title, docs, ai-prompt, includes, prefix, postfix, theme |
md2gost.styles.json |
рядом с .md или путь в --styles |
оверлей оформления поверх пресета |
info_conv.yaml |
рядом с .md |
институт, кафедра, дисциплина, преподаватель, должность |
.md2gost-cache/ |
рядом с .md |
кэш отрисованных диаграмм |
md2gost.include-cache.json, include-cache/ |
рядом с приложением | кэш скачанных .puml |
Приоритет загрузки, где каждый следующий слой сильнее: встроенный шаблон → файл рядом с приложением → файл рядом с .md → явный путь в ключе.
info_conv.yaml
Институт: Институт информационных технологий (ИИТ)
Кафедра: Кафедра цифровой трансформации (ЦТ)
Дисциплина: Проектирование архитектуры цифровой организации
Преподаватель: Иванов Иван Иванович
Должность: старший преподаватель, кафедра ЦТ
Плоский список ключ: значение в UTF-8. Строки с # — комментарии. ФИО и группа студента из файла не читаются: они берутся из профиля или ключей --student / --group.
Автотитул: условия срабатывания
- Включён
--auto-title(или галочка «Автотитул»). - Не задан готовый
--title. - Есть
info_conv.yamlрядом с.mdили блок```titleв начале файла. - Известны ФИО и группа — иначе конвертация останавливается с подсказкой «Для генерации титула нужны ФИО и группа студента».
Номер работы и год берутся из блока ```title (number, year); значения из блока сильнее info_conv.yaml. По умолчанию номер 1, год — текущий.
md2gost.styles.json
{
"page": { "left_mm": 30, "right_mm": 10, "top_mm": 20, "bottom_mm": 20 },
"styles": {
"Heading 1": { "alignment": "center", "size_pt": 14, "all_caps": true }
}
}
Допустимые имена стилей: Normal, Heading 1, Heading 2, Heading 3, Caption Figure, Caption Table, Название таблицы, Caption Listing, Caption, Code, Table Text, Bibliography, Bibliography Heading, toc 1, toc 2, toc 3, Footer, Hyperlink, FollowedHyperlink, Space After Table.
Допустимые поля стиля: font_name, size_pt, bold, italic, all_caps, underline, alignment (left / center / justify), first_line_indent_cm, left_indent_cm, right_indent_cm, space_before_mm, space_after_mm, line_spacing (1.0 / 1.5), page_break_before, keep_with_next, widow_control.
Неизвестный ключ или неизвестное имя стиля — ошибка запуска. Не настраивается через JSON: табуляция оглавления, отступы списков, оформление формул, цвет текста (всегда чёрный).
7. Переменные окружения
| Переменная | Назначение |
|---|---|
PLANTUML_JAR |
путь к plantuml.jar |
KROKI_URL |
адрес локального Kroki, по умолчанию http://localhost:8000 |
PLAYWRIGHT_BROWSERS_PATH |
каталог Chromium для Mermaid |
WORKING_DIR |
родительский каталог кэша диаграмм |
8. Где что в окне
| Меню | Содержимое |
|---|---|
| Основные | тип документа, выходной путь, нумерация заголовков, содержание, режимы продолжения таблиц и листингов, смещение страниц |
| Настройки → Файлы | шаблон, титульный лист, бланк задания, стили JSON |
| Настройки → Студент | ФИО и группа (спрашиваются при первом запуске) |
| Настройки → Метаданные | свойства DOCX |
| Настройки → Диаграммы | PlantUML, Graphviz для DFD, Chromium для Mermaid, Kroki, формат, сброс кэша |
| Шаблоны UML | редактор md2gost.schemes.json |
| Справка | инструкция, документация, схемы, промпт для ИИ |
Кнопка «Импорт DOCX→MD» и перетаскивание .docx запускают импорт; перетаскивание .md подставляет файл для сборки.
9. Установка
pip install -e .
pip install pywin32 # Windows: продолжение таблиц через Word COM
Нужен Python 3.10 или новее (для DFD — 3.11 и новее). Для PlantUML нужна Java; для Mermaid — Chrome, Edge или скачиваемый Chromium; для DFD — Graphviz. IDEF0 рисуется локально без внешних зависимостей.