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

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

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

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

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

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

build_graph

Macros permissions: FILE_READING, PASS_ARGUMENTS

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

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

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

color

Macros permissions: PASS_ARGUMENTS

Позволяет поменять цвет текста. Цвет задаётся в формате RGB:

`color(255,0,0): Красный текст`
`color(0,255,0): Зелёный текст`

count_appendix

count_formulas

count_images

count_sources

count_tables

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

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

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

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

formula

Macros permissions: ADD_VARIABLES, PASS_ARGUMENTS

formula_describe

Macros permissions: 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

Macros permissions: 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): Что-то тут не понравилось. а где задача? Где?`

listing

Macros permissions: ADD_VARIABLES, FILE_READING, PASS_ARGUMENTS

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

`listing: ./info.txt`

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

mention

Macros permissions: READ_VARIABLES, PASS_ARGUMENTS

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

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

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

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

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

page_break

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

print_plain_text

Macros permissions: FILE_READING, PYTHON_EXECUTION, PASS_ARGUMENTS

Позволяет выполнить код 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_list_digit

Macros permissions: SETTINGS_CHANGE, PASS_ARGUMENTS

set_list_marker

Macros permissions: 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

Macros permissions: READ_VARIABLES

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

store_var

Macros permissions: ADD_VARIABLES, PASS_ARGUMENTS

store_var_return

Macros permissions: ADD_VARIABLES, READ_VARIABLES, PASS_ARGUMENTS

var

Macros permissions: READ_VARIABLES, PASS_ARGUMENTS

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

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

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

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

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

table_name

Macros permissions: SETTINGS_CHANGE, PASS_ARGUMENTS

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

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

table_of_contents

Macros permissions: READ_VARIABLES

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

today

Macros permissions: PASS_ARGUMENTS, EXPRESSION_EVALUATION

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

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

TODO

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

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

work_interval

Macros permissions: EDIT_VARIABLES, PASS_ARGUMENTS

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

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

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

`work_interval(12.02.2025, 30.05.2025)`