md2gost

Скрипт для генерации отчёта в формате DOCX по ГОСТ из Markdown-файла.

Roadmap проекта

HTTP-сервер (интеграция с GostForge)

В md2gost встроен FastAPI HTTP-сервер для интеграции с backend GostForge.

Запуск сервера

# Через entry point
md2gost-server

# Либо напрямую
python -m md2gost.server

# Через Docker
docker build -t md2gost .
docker run -p 8000:8000 md2gost

API endpoints

Endpoint	Метод	Описание
/health	GET	Проверка доступности сервиса
/config/reference	GET	Эталонные параметры Md2GostConfig с описаниями и значениями по умолчанию
/convert	POST	Синхронная конвертация Markdown → DOCX
/jobs	POST	Создание асинхронной задачи (ответ 202)
/jobs/{id}	GET	Получение статуса задачи
/jobs/{id}/result	GET	Скачивание результата завершённой задачи

Переменные окружения

Переменная	По умолчанию	Описание
MD2GOST_HOST	0.0.0.0	Хост, на котором слушает сервер
MD2GOST_PORT	8000	Порт сервера
MD2GOST_WORKERS	1	Число worker-процессов uvicorn для параллельной обработки запросов

Поддержка callback URL

При создании асинхронной задачи через POST /jobs можно передать поле формы callback_url. После завершения задачи (или ошибки) сервер выполнит POST c JSON-статусом на указанный URL.

---

Основные возможности

• Генерация отчёта;
• Добавление титульной страницы в формате DOCX;
• Настройка генератора через gostforge.yml;
• Генерация интерактивного содержания;
• Поддержка сквозной нумерации и кросс-референсов;
• Автоматическая нумерация рисунков, продолжений таблиц, листингов и т.д.

Пример

Markdown-файл: example.md

Сгенерированный файл в ZIP-архиве (команда python -m md2gost --syntax-highlighting example.md): example.zip

Установка

pip install --upgrade git+https://github.com/witelokk/md2gost.git@main

Если ваша система использует стандарт PEP 668, рекомендуется pipx:

pipx install git+https://github.com/witelokk/md2gost.git@main

Использование

(python -m ) md2gost [-h] [-o OUTPUT] [-T TITLE] [-c CONFIG] [--syntax-highlighting | --no-syntax-highlighting] [--debug] [filenames ...]

Если флаг -o не указан, итоговый отчёт создаётся с именем исходного файла и расширением .docx.

Фичи

Конфигурация через gostforge.yml

md2gost может читать параметры генерации из gostforge.yml.

Поддерживаются:

• как корневые ключи,
• так и секции md2gost и md2gost.generator.

Пример:

md2gost:
  title_pages: 2
  syntax_highlighting: true
  sectional_numbering: true
  page_margin_left: 2.5cm
  font_size_main: 13pt
  caption_separator: " — "
  caption_image_style: "bold"

title_pages задаётся через gostforge.yml.

Добавление титульной страницы

Чтобы добавить титульную страницу, используйте флаг --title (-T) с путём к DOCX-файлу титульника. Если в документе больше одной страницы, укажите количество через title_pages в gostforge.yml.

Пример:

md2gost report.md --title title.docx

Подписи рисунков, листингов, таблиц

Рисунки:

![](path/to/image "%unique_name Текст подписи")

Таблицы:

%uniquename Текст подписи

| a | b | c |
|---|---|---|
| a | b | c |

Листинги:

%uniquename Текст подписи

```python
print("hello world")
```

Формулы:

%uniquename

$$
2 + 2 = 4
$$

uniquename — уникальное имя для кросс-ссылок.

Ссылки

Чтобы вставить кликабельный номер рисунка/листинга/таблицы, используйте:

Рис. @unique_name

Заголовки основных разделов без нумерации

Чтобы заголовок был без сквозной нумерации (например, «СОДЕРЖАНИЕ»), используйте:

# *СОДЕРЖАНИЕ

Генерация содержания

[TOC]

Подсветка синтаксиса в листингах

Используйте флаг --syntax-highlighting.

Импорт кода в листингах

```python code.py
```

где code.py — путь к файлу с исходным кодом.