В качестве расширения функционала конвертера библиотекой предусмотрены макросы, расширяющие возможности Markdown — от создания переменных до выполнения кода Python. Каждый макрос требует определённых прав. У некоторых макросов указаны также дополнительные права — они нужны только для отдельных вариантов вызова: без них макрос всё равно работает, но такой вариант пропускается, о чём сообщается в результате сборки. Список всех текущих макросов представлен ниже.

Синтаксис макросов

Макрос — это встроенный вызов внутри обратных кавычек (`). Общий вид:

`имя_макроса`
`имя_макроса: значение`
`имя_макроса(аргумент1,аргумент2)`
`имя_макроса(аргумент1,аргумент2, ...): значение`

• Имя — обязательная часть, определяет, какой макрос вызывается.
• Аргументы — необязательные параметры в круглых скобках, разделённые запятой. Пробелы внутри аргументов сохраняются и являются значимыми.
• Значение — текст после двоеточия. У некоторых макросов это основное содержимое (например, текст переменной или путь к файлу), у других поле значения не используется.

Описание макросов

build_graph

Обязательные права: FILE_READING, PASS_ARGUMENTS, TOOLS

Используя инструментарий Graphviz позволяет создавать графы на основе языка описания графов DOT.

```build_graph
digraph "Потребители, курьеры и заказы" {
    rankdir=LR
    "Частота заказов" -> "Потребители"
    "Потребители" -> "Чаще заказывать"
        "Чаще заказывать" -> "Фильтр"
        "Чаще заказывать" -> "Подсказки"
    "Потребители" -> "Оставлять отзыв"
        "Оставлять отзыв" -> "\"Технический момент\""
        "Оставлять отзыв" -> "Система лояльности"
    "Потребители" -> "Привести друга"
        "Привести друга" -> "Система лояльности"
    "Частота заказов" -> "Курьеры"
        "Курьеры" -> "Скорость выполнения заказов"
            "Скорость выполнения заказов" -> "Система мотивации"
        "Курьеры" -> "Кол-во"
            "Кол-во" -> "Система мотивации"
}
```

Для наименования графов следует изменять имя самого графа — как выше указано "Потребители, курьеры и заказы". При наличии нескольких графов рисунок именуется по первому из них.

citations_as_footnotes

Оформляет ссылки на источники постраничными сносками вместо номеров [N]. Так требуют некоторые кафедры, чаще всего юридические. Аргументов нет. Макрос действует на весь документ, где бы он ни стоял, включая ссылки выше него, поэтому его пишут в начале, рядом с другими настройками:

`include(titul.docx, section)`
`work_interval(01.02.2026, 30.05.2026)`
`citations_as_footnotes`

• Каждая ссылка [[ключ]](url) становится знаком сноски сразу после слова, к которому относится (пробел перед ссылкой убирается). В сноске — полная строка источника. Нумерация сносок начинается заново на каждой странице.
• Повторная ссылка — снова полная сноска, никогда не «Там же»: так сноска остаётся верной при любой разбивке на страницы.
• Место в источнике ставится перед URL. Номер страницы заменяет диапазон страниц статьи: [[Адаменко|78]] даёт

¹ Адаменко, А. П. Банкротство индивидуальных предпринимателей – правовые проблемы / А. П. Адаменко // Имущественные отношения в РФ. – 2025. – №8 (287). – С. 78. — URL: https://cyberleninka.ru/article/n/... (дата обращения: 14.03.2026).

• Другое место дописывается перед URL с заглавной буквы: … // КонсультантПлюс : справочно-правовая система. Ст. 5. — URL: ….
• Список источников остаётся прежним: каждый источник один раз, в порядке первого упоминания, без мест в источнике. Дата обращения в сноске и в списке совпадает.
• Смешивать сноски и номера [N] нельзя: макрос превращает в сноски все ссылки документа.

color

Обязательные права: PASS_ARGUMENTS

Позволяет поменять цвет текста. Цвет задаётся в формате RGB, HEX или именем — теми же, что у highlight_color:

`color(255,0,0): Красный текст`
`color(#00FF00): Зелёный текст`
`color(DARK_BLUE): Тёмно-синий текст`

Если цвет не распознан, текст вставляется без цвета, а в результате сборки появляется предупреждение.

comment

Ничего не делает: при сборке макрос удаляется из документа вместе со своим значением. Это способ оставить заметку, которая остаётся в исходнике, но не попадает в docx.

`comment: черновик, переписать`

count_appendix

count_formulas

count_images

count_sources

count_tables

Выводит количество рисунков / таблиц / формул и других сущностей в документ:

Документ включает в себя `count_images` рисунков и `count_tables` таблиц.

Все макросы-счётчики:

• count_appendix — количество приложений (листингов, созданных макросом listing)
• count_formulas — количество формул
• count_images — количество изображений (картинок)
• count_sources — количество источников (номер последнего источника)
• count_tables — количество таблиц

formula

Обязательные права: ADD_VARIABLES, PASS_ARGUMENTS

formula_describe

Обязательные права: PASS_ARGUMENTS

formula генерирует формулу из LaTeX. После него можно вызывать formula_describe для описания переменных:

`formula(число ошибок): N=n\frac{S}{v}`
`formula_describe(n — найденные собственные ошибки, S — всего внесённых ошибок, v — найденные внесённые ошибки)`

`formula(*число ошибок2): N=2\frac{10}{6}=3,(6)`

`formula(число необнаруженных ошибок): (N-n)=3,6-2=1,6`

`formula(формула соотношения): p=\frac{1,6}{1,6+K+1}=\frac{5}{5+0+1}=0,615`

Если перед именем формулы стоит *, счётчик нумерации не увеличивается. Следующая формула без * получит тот же номер. Это удобно, когда нужно показать подстановку конкретных значений в формулу без присвоения ей отдельного порядкового номера.

highlight_color

Обязательные права: PASS_ARGUMENTS

Позволяет поменять цвет фона текста. В качестве аргумента принимаются константы из WD_COLOR_INDEX:

AUTO, BLACK, BLUE, BRIGHT_GREEN, CYAN, DARK_BLUE, DARK_CYAN, DARK_RED, DARK_YELLOW, GRAY_25, GRAY_50, GREEN, MAGENTA, NONE, PINK, RED, TEAL, TURQUOISE, VIOLET, WHITE, YELLOW

`highlight_color(YELLOW): Что-то тут не понравилось. а где задача? Где?`

include

Обязательные права: FILE_READING

Дополнительные права: NETWORK_ACCESS

Вставляет на место макроса содержимое другого файла. Обе формы вызова равнозначны:

`include: путь/к/файлу.md`
`include(путь/к/файлу.md)`

Путь указывается относительно файла, в котором написан макрос, — поэтому вложенные include внутри уже включённого файла тоже работают. Файл вне папки документа (../shared.md, абсолютный путь) подключается только через MGost CLI — см. ЧаВо.

Поведение зависит от расширения файла:

• .md, .markdown — файл разбирается как Markdown и вставляется так, как если бы его текст был написан на месте макроса. Относительные пути внутри включённого файла (изображения, листинги, вложенные include) переписываются, чтобы продолжать указывать на нужные файлы.
• .txt — вставляется как обычный текст: пустые строки разделяют абзацы, Markdown не интерпретируется.
• .docx — тело документа копируется вместе с его стилями, списками, таблицами, изображениями и ссылками. Вставленный текст выглядит так же, как в Word, а не по ГОСТ. Колонтитулы, сноски, комментарии и диаграммы не переносятся.
• Любое другое расширение отклоняется с предупреждением.

Макрос пишется отдельной строкой: внутри абзаца или таблицы он разрывает текст вокруг себя.

Аргумент section (только для .docx) сохраняет ещё и параметры страницы файла: поля, размер, ориентацию. Вставка становится отдельным разделом, после неё документ продолжается с новой страницы с полями по ГОСТ. Так добавляются титульный лист и задание, выданные кафедрой:

`include(titul.docx, section)`

`include(zadanie.docx, section)`

# **Содержание
`table_of_contents`

Без section файл вставляется в текущий раздел — так удобно вставлять фрагменты, например таблицу.

Вместо пути можно указать адрес, начинающийся с https://: файл скачивается один раз в проект, переиспользуется при следующих сборках и включается точно так же, как локальный. Для этого помимо FILE_READING нужно дополнительное право NETWORK_ACCESS. Два разных адреса, оканчивающихся одинаковым именем файла, в одном проекте включить нельзя: второй будет отклонён с предупреждением, а не перезапишет первый.

Ничего не вставляется, а в результате сборки появляется предупреждение, если:

• включение циклическое — файл напрямую или через другие файлы включает сам себя;
• файл не найден — то же предупреждение, что и у listing.

Структура файлов в примере

├── main.md
├── intro.md
├── appendix.docx

intro.md

## Введение

Этот раздел написан в отдельном файле.

main.md

`include: intro.md`

## Основная часть

Текст основной части.

`include: appendix.docx`

В результате out.docx начинается с раздела «Введение», за ним идёт «Основная часть», а в конце — содержимое appendix.docx.

listing

Обязательные права: ADD_VARIABLES, FILE_READING, PASS_ARGUMENTS

Позволяет вставить листинг на месте макроса. Заголовок раздела данным макросом не создаётся, над листингом ставится подпись «Листинг N. Название». Пример использования:

`listing: ./info.txt`
`listing(Пример структуры сохранения): ./info.txt`
`listing(*Продолжение примера): ./info2.txt`

Если файл info.txt, лежащий рядом с main.md, существует, его содержимое будет вставлено в документ в виде листинга. Если файл не найден, вставка не произойдёт — в интерфейсе появится предупреждение.

Единственный аргумент — название листинга, по нему листинг можно упомянуть через mention. Без аргумента названием становится имя файла. Листинги нумеруются сквозной нумерацией по всему документу, без номера главы: обычно они находятся в приложениях. Если название начинается с *, листинг получает номер предыдущего.

mention

Обязательные права: READ_VARIABLES, PASS_ARGUMENTS

Позволяет упомянуть рисунок, таблицу или формулу по её названию. Так как данный макрос срабатывает после генерации всего документа, в него нельзя вставить какие-либо макросы, но он позволяет упомянуть любой рисунок / таблицу / формулу независимо от позиции:

Упоминание до: `mention: Главный поток данных`
Неполное упоминание до: `mention: Главный поток`

![Главный поток данных](./DFD_Data.png)

Упоминание после: `mention: Главный поток данных`
Неполное упоминание после: `mention: Главный поток`

При неполном упоминании выбирается первая переменная, имя которой начинается с указанной строки. Если два объекта имеют схожие начала названий, будет выбран тот, что зарегистрирован раньше.

По умолчанию макрос выводит сокращение и номер — например, Рис. 1.1 или Табл. 2.3. Аргумент only_number оставляет только номер, что удобно, когда слово уже написано в тексте:

Сравнение приведено в таблице `mention(only_number): Сравнение языков`.

orientation

Меняет ориентацию страниц. Принимает ровно один аргумент:

• landscape — альбомная
• portrait — книжная

Всё, что идёт после макроса, начинается с новой страницы в выбранной ориентации, поэтому page_break перед ним не нужен. Поля не меняются: переплётное поле (левое, 30 мм) остаётся на том же месте. Изображения после макроса вписываются в страницу уже новой ориентации.

`orientation(landscape)`

# Журнал

...

`orientation(portrait)`

• Макрос в самом начале документа меняет ориентацию первой страницы без разрыва.
• Повторный макрос с той же ориентацией игнорируется, в результате сборки появляется информационное сообщение.
• Любой другой аргумент — ошибка, макрос ничего не вставляет.

page_break

Вставляет разрыв страницы на месте макроса. Служебный макрос.

page_numbers

Ставит номера страниц внизу по центру. Без этого макроса номеров страниц в документе нет. Аргумент — вид номеров:

• arabic — 1, 2, 3
• roman_lower — i, ii, iii
• roman_upper — I, II, III

Без аргумента макрос скрывает номера с этого места, но страницы продолжают считаться. Неизвестный аргумент игнорируется с информационным сообщением. Нумерация сквозная по всему документу: титульный лист из include(titul.docx, section) — страница 1.

ГОСТ 7.32 требует номера внизу по центру, а титульный лист считать, но не нумеровать. Так и выйдет, если поставить макрос в начале, выше содержания:

`include(titul.docx, section)`
`page_numbers(arabic)`

# **Содержание
`table_of_contents`

# **Введение

MGost знает, где точно начинается новая страница: заголовок #, page_break отдельной строкой, orientation, include(…, section). Поэтому номера включаются только в одном из этих мест:

• Макрос выше table_of_contents — номера начинаются с первой новой страницы после содержания (обычно со следующего #). Титульный лист и содержание считаются, но без номеров. Это обычный случай.
• Макрос ниже содержания или в документе без содержания — номера начинаются с последней новой страницы до макроса. Чтобы не ошибиться, ставьте его сразу под заголовком #.

print_plain_text

Обязательные права: FILE_READING, PYTHON_EXECUTION, PASS_ARGUMENTS, TOOLS

Позволяет выполнить код Python, а вывод print() записать вместо макроса в конечном документе.

Внимание. Данная функция выполняет произвольный код Python, поэтому в ряде случаев следует ограничить доступ обычных пользователей к этой функции. Выполняется асинхронно — во время создания docx, результат получается в момент его сохранения.

Структура файлов в примере

├── main.md
├── counter.py

counter.py

for i in range(0, 21):
    print(i, end=',')

main.md

Считаем от 0 до 20: `print_plain_text: counter.py` круто!

Выполняем рендер. Результат в out.docx: Считаем от 0 до 20: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20, круто!

set_hyphenation

Включает автоматические переносы слов. Без этого макроса переносов в документе нет. Аргументов нет. Действует на весь документ, где бы ни стоял, поэтому его пишут в начале. Заголовки не переносятся никогда (ГОСТ 7.32).

`set_hyphenation`

set_image_dpi

Обязательные права: SETTINGS_CHANGE, PASS_ARGUMENTS

Задаёт плотность пикселей (DPI), до которой уменьшаются изображения. Аргумент — целое число от 72 до 300, по умолчанию 150. Размер изображения на странице макрос не меняет (см. ЧаВо), он определяет только, сколько пикселей хранится в документе: если их больше, чем нужно для выбранного DPI при этом размере, изображение уменьшается, иначе файл вставляется как есть.

`set_image_dpi(300)`

Макрос действует на все изображения после него, поэтому его стоит писать в начале документа. Работает и внутри файлов, подключённых через include, и остаётся в силе после них. Значение вне диапазона игнорируется с информационным сообщением.

set_list_digit

Обязательные права: SETTINGS_CHANGE

Дополнительные права: PASS_ARGUMENTS

set_list_marker

Обязательные права: SETTINGS_CHANGE

Дополнительные права: PASS_ARGUMENTS

Эти два макроса позволяют менять формат нумерованных и маркированных списков. MGost не использует встроенные списки Docx (из-за известных проблем python-docx с нумерацией), а отсчитывает отступы самостоятельно согласно ГОСТ. В обычной ситуации использование этих макросов не требуется, так как значения по умолчанию уже следуют MGost.

У обоих макросов следующие аргументы:

1. Символ до текста
2. Окончание текста (кроме последнего элемента!)
3. Окончание текста последнего элемента

В отличие от set_list_marker, у set_list_digit первый аргумент может содержать {counter} — подстановку автоинкрементного счётчика.

`set_list_marker(—,;,.)`
`set_list_digit({counter}.,.,;)`

sources

Обязательные права: READ_VARIABLES

Дополнительные права: PASS_ARGUMENTS, NETWORK_ACCESS

Вставляет список источников, сформированный на основе ссылок внутри документа. Ссылки автоматически дополняются названием страницы, полученным из HTML-заголовка, и оформляются по ГОСТ. В качестве первого аргумента можно указать число, с которого начинается отсчёт (если вы вручную добавляете часть источников). Для добавления умных источников обратитесь к разделу ЧаВо, вид строки источника описан там же. Ссылки внутри ячеек таблиц не собираются: в ячейке останется [ключ], а источника не будет в списке. Ссылайтесь в тексте до или после таблицы.

store_var

Обязательные права: ADD_VARIABLES, PASS_ARGUMENTS

store_var_return

Обязательные права: ADD_VARIABLES, READ_VARIABLES, PASS_ARGUMENTS

var

Обязательные права: READ_VARIABLES, PASS_ARGUMENTS

Три макроса для создания и переиспользования переменных в документе Word. Если какое-то предложение повторяется, его можно сохранить в переменную при первом использовании и подставлять далее — изменение в одном месте обновит все вхождения.

store_var_return — сохраняет значение и вставляет его на место макроса

### **Аннотация
В исследовательском разделе `store_var_return(исследовательский_старт): анализируется предметная область, существующие решения, устанавливаются цели, задачи и техническое задание.`
...
# Исследовательский раздел
В данном разделе `var(исследовательский_старт)`

store_var — сохраняет значение без вставки

### **Аннотация
`store_var(исследовательский_старт): анализируется предметная область, существующие решения, устанавливаются цели, задачи и техническое задание.`
В исследовательском разделе `var(исследовательский_старт)`
...
# Исследовательский раздел
В данном разделе `var(исследовательский_старт)`

table_name

Обязательные права: SETTINGS_CHANGE, PASS_ARGUMENTS

Сохраняет название для следующей таблицы, которую встретит рендер. Макрос может находиться в любом месте документа — не обязательно непосредственно перед таблицей.

`table_name: Типы данных динамического объекта`
|        Поле       |   Тип   |
|-------------------|---------|
| Позиция           | вектор  |
| Скорость          | вектор  |
| Поворот           | ротатор |
| Скорость поворота | вектор  |

table_of_contents

Обязательные права: READ_VARIABLES

Вставляет содержание на место макроса. Количество использований неограничено, однако по ГОСТу следует ставить после заголовка «Содержание».

today

Обязательные права: PASS_ARGUMENTS, EXPRESSION_EVALUATION

Вставляет текущую дату и/или время в документ.

Для форматирования используется метод Python strftime.

TODO

Обязательные права: PASS_ARGUMENTS

Макрос-помощник. При встрече рендера с данным макросом MGost удаляет его из документа и создаёт уведомление, которое отображается в интерфейсе сайта:

`TODO: доделать макияж`

work_interval

Обязательные права: EDIT_VARIABLES, PASS_ARGUMENTS

Указывает временной диапазон написания документа. Используется для всего автоматического заполнения, где задействованы даты (например, время обращения к онлайн-ресурсам при заполнении списка источников). Поле значения игнорируется; принимает от 1 до 2 аргументов:

1. Начальная дата — конечная дата устанавливается текущим днём.
2. Начальная и конечная дата.

По умолчанию конечной датой считается текущее число, начальной — день неделю назад.

`work_interval(12.02.2025, 30.05.2025)`