# MGost

> MGost converts one Markdown file (plus the files it references) into a `.docx` formatted to ГОСТ 7.32: styles, margins, numbering of headings, figures, tables, formulas and listings, the table of contents and the bibliography are all produced automatically. It runs on https://articha.ru/mgost/ and through the `mgost` CLI from PyPI.

This file is for AI agents. It covers writing Markdown for MGost, every macro, how a build runs, permissions, and the CLI. Human docs (Russian): [overview](https://articha.ru/mgost/user_docs/), [macros](https://articha.ru/mgost/user_docs/macros/), [FAQ](https://articha.ru/mgost/user_docs/faq/), [annotated example](https://articha.ru/mgost/user_docs/example/).

## Ground rules

- MGost is a **converter**: the `.docx` contains only what the `.md` says. An empty `.md` gives an empty `.docx`. The title page is not written in Markdown: the user makes it in Word and adds it with `include(title.docx, section)`.
- **Styles are automatic. Don't fight them.** Do not emulate fonts, sizes, indents, alignment, numbering or captions by hand. Never type `1.2`, `Рисунок 1.1 —`, `Таблица 2.3 —`, `(1.1)` or `[3]`: MGost generates them.
- **Never format the bibliography yourself.** Cite with `[[key]](url)` and place the `sources` macro. If ГОСТ rules for sources change, MGost changes, and hand-written entries do not. Agents also get ГОСТ source formatting wrong. The only exception is sources with no URL, see [Sources](#sources).
- Input is [GitHub Flavored Markdown](https://github.github.com/gfm/) plus macros. Headings beyond `###`, fenced code blocks, and ГОСТ-unrelated tricks are covered below.
- Document text is normally Russian. Generated captions are Russian (`Рисунок`, `Таблица`, `Листинг`).
- Not every user writes a ГОСТ academic work. When the user says they only want a plain `.md` → `.docx` conversion, skip the academic skeleton below. Everything else still applies.

## How a build runs

1. **Parse.** The Markdown (with every `include`d file) is parsed into a DOM of Python classes. Macros that run *while parsing* execute now and are replaced by DOM elements.
2. **Media check.** Every referenced image is opened. Missing or broken ones are marked unavailable.
3. **Numbering.** One pass in document order assigns every number: headings, figures, tables, formulas, listings, sources. This is why `mention` works before or after its target.
4. **Write.** The DOM is written into a `python-docx` document. Macros that run *while writing* execute now, in document order: settings macros affect only what follows them.
5. **After writing.** Macros that run *after the document is written* edit the finished `python-docx` document (counters, `print_plain_text` output). Then the file is saved.

Problems never abort a build. Each one becomes a log entry (`info`, `warning`, `error`) shown to the user on the site or in the CLI output, and the element at fault is dropped or rendered without the failing part. Read the log after every build.

## Document skeleton

For a ГОСТ work (курсовая, ВКР, отчёт), always include `# **Содержание` + `table_of_contents` and `# **Список использованных источников` + `sources`. Other sections depend on what the university requires: ask the user or follow their regulations.

```md
`include(title.docx, section)`

`work_interval(01.02.2026, 30.05.2026)`

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

# **Введение
# Первая глава
## Параграф
### Пункт
# Вторая глава
# **Заключение
# **Список использованных источников
`sources`
```

- The title page (and the assignment page, if required) comes first: `include(file.docx, section)`, one per file, each on its own line.
- Document-wide macros (`work_interval`, `set_image_dpi`) go right after it.
- Unnumbered structural sections (Аннотация, Содержание, Введение, Заключение, sources) are `# **`.
- Optional sections, added only when the work needs them: `# **Аннотация`, `# **Список используемых сокращений`, appendices.
- Appendices are written by hand. A common layout is `# **Приложения` listing them, then each appendix as `## **Приложение А - …`, usually holding a `listing`. `##` does not start a new page, so this is the one place for `page_break`:

```md
# **Приложения
Приложение А - Название

`page_break`

## **Приложение А - Название
`listing(Название): ./code/file.py`
```
- HTML comments `<!-- … -->` are dropped from the output. Use them for notes to the author or to yourself; `comment` and `TODO` macros are alternatives.

## Headings

Levels `#`, `##`, `###`. Deeper levels (`####`…) are clamped to `###`. `#` starts a new page; `##` and `###` do not.

| Markdown | Number shown | Advances counter | Alignment |
|---|---|---|---|
| `# Глава` | yes (`1`, `1.1`, `1.1.1`) | yes | paragraph indent, like body text |
| `# *Глава` | no | yes | centered |
| `# **Глава` | no | no | centered |

The same holds for `##` and `###`. h1 is printed in capitals.

- Every heading appears in the table of contents (except an h1 named exactly `Содержание`). h1 lines are upper-cased there.
- Use `**` for unnumbered sections. `*` hides the number but still consumes it: `# *Введение` followed by `# Глава` makes the chapter `2`.
- Skipping a level (`#` then `###`) produces a warning.
- Duplicate heading text works but gets a warning.

## Paragraphs, lists, emphasis

Normal GFM. Bold, italic and inline links render normally. A link becomes a source only in the `[[key]](url)` form.

Lists follow ГОСТ by default: indents, markers and item endings. A wrong ending (`,` `;` `:` `.`) is corrected with a warning: `- пункт.` in the middle of a list becomes `пункт;`, and the last item always ends with `.`. Items ending with `?`, `!` or `…` are left as written. Write items without worrying about `;`/`.`. Don't use `set_list_marker` / `set_list_digit` for ГОСТ lists; they exist for the rare non-ГОСТ list.

## Code blocks

ГОСТ does not allow code blocks in the text. A fenced block is only a carrier for a macro, whose name is the fence language (` ```build_graph `). Any other fence, e.g. ` ```python `, is not rendered: the document gets just the word `python` and a warning. Put program code in an appendix with `listing`.

## Media: figures, tables, formulas, listings

All media share **one namespace of names**, which `mention` uses. Give every figure, table, formula and listing a unique name.

Figures, tables and formulas are numbered **per chapter** (`chapter.n`, the chapter is the current h1 counter). Listings are numbered **document-wide** (`Листинг 1.`), because they live in the appendix.

| Media | Created by | Caption in `.docx` |
|---|---|---|
| Figure | `![Name](path)` or `build_graph` | `Рисунок 1.1 — Name` below |
| Table | Markdown/HTML table, named by `table_name` | `Таблица 1.1 — Name` above |
| Formula | `formula(Name): LaTeX` | `(1.1)` at the right |
| Listing | `listing(Name): path` | `Листинг 1. Name` above |

### Images

```md
![Схема модулей](./img/modules.png)
```

- The alt text is the caption and the name. It must not be empty, or the image is skipped.
- Paths are relative to the `.md` file that contains them.
- Any common raster format (PNG, JPEG, GIF, BMP, WEBP, TIFF). SVG and PDF are rejected; draw diagrams with `build_graph` or export PNG.
- Shown at natural size (96 px per inch), shrunk to fit the page, never enlarged. Pixel density is reduced to `set_image_dpi` (default 150).
- Missing file: a warning, nothing inserted. Broken file: an error, nothing inserted, numbering continues without a gap.

### Tables

Write `table_name: Name` anywhere before the table. It names the **next** table the parser meets.

```md
`table_name: Сравнение решений`

| Решение | Цена |
|---------|------|
| Jira    | 10   |
```

- Markdown tables: the first row is the centered header, other rows are justified.
- HTML tables add merged cells and alignment. Header rows are those in `<thead>`, or else the leading rows made only of `<th>`. `colspan` extends right, `rowspan` extends down; cells covered by a merge are skipped in the markup, as in a browser.
- `align="XY"` on a cell: X is horizontal (`l`/`s` left, `c`/`m` center, `r`/`e` right, `j` justify, `d` distribute), Y is vertical (`t`/`s` top, `c`/`m` middle, `b`/`e` bottom). Example: `<td align="cc">`.
- Two `table_name` before one table: the second wins and the first is lost. A table with no name gets `Без названия` and a warning.

```html
<table>
    <tr><th rowspan="2">№</th><th colspan="2">Показатель</th></tr>
    <tr><th>План</th><th>Факт</th></tr>
    <tr><td align="cc">1</td><td>10</td><td>12</td></tr>
</table>
```

### Formulas

```md
`formula(нагрузка): N=\frac{R}{t}`
`formula_describe(R — число запросов, t — время в секундах)`
`formula(*нагрузка2): N=\frac{100}{4}=25`
```

- The argument is the name; the value is LaTeX. It must be written on one line.
- A name starting with `*` repeats the previous formula's number instead of taking a new one (use it for substituting numbers into a formula).
- `formula_describe` is independent of `formula`: it prints a ГОСТ-styled «где …» block, one line per comma-separated argument. Use it to name each symbol concisely (`R — число запросов`). Write any longer explanation as a normal paragraph after it.

### Listings

```md
`listing(Сервис заявок): ./code/service.py`
`listing: ./code/service.py`
`listing(*Продолжение сервиса): ./code/service2.py`
```

- The argument is the caption and the name. Without it, the file name is used.
- `*` before the name repeats the previous listing number.
- The file content is inserted as plain text in a framed cell. `count_appendix` counts listings.

### Mentions

```md
Результаты приведены в таблице `mention(only_number): Сравнение решений`.
Поток данных показан на `mention: Поток данных`.
```

- `mention: Name` prints a noun and the number: `Рис. 1.1`, `Табл. 1.1`, `Формула 1.1`, `Листинг 1`. `mention(only_number): Name` prints just the number. Use `only_number` after your own word («в таблице 1.1»).
- Works regardless of position.
- A prefix is enough (`mention: Поток`); the first media registered with that prefix wins. Prefer full names.
- Unknown name, or a target that failed (missing image): an error, nothing printed.

## Sources

Cite inline with a double-bracket key. Each citation becomes `[N]`; the `sources` macro prints the ГОСТ list.

```md
Популярность языков приведена на сайте [[TIOBE]](https://www.tiobe.com/tiobe-index/).
Повторная ссылка [[TIOBE]](https://www.tiobe.com/tiobe-index/) получит тот же номер.
Своё название: [[pep8]](https://peps.python.org/pep-0008/ "PEP 8 — Style Guide for Python Code").

# **Список использованных источников
`sources`
```

- The key inside `[[…]]` merges repeated citations and never appears in the document. Any text works: `[[1]]`, `[[ГК]]`, `[[TIOBE]]`.
- Repeat the full `[[key]](url)` at every citation, never a bare `[N]`. Each citation carries its source, so deleting text never leaves a dangling number: a source disappears from the list together with its last citation.
- Without a quoted title, MGost fetches the page `<title>`. It works only for sites that return full HTML without bot checks. SPAs, Cloudflare-protected or login-only pages give nothing useful: give the title in quotes.
- The access date («дата обращения») is a random day within the `work_interval` range.
- To point at a place inside a source (article, clause, page), name it in the sentence: `Согласно статье 223 ГК РФ [[ГК]](url) …`. Don't put it in the key: `[[ГК, ст. 223]]` is a different key and duplicates the source.

MGost writes every entry itself. The citation `[[pep8]](https://peps.python.org/pep-0008/ "PEP 8 — Style Guide for Python Code")` becomes:

```text
1.	«PEP 8 — Style Guide for Python Code», [Электронный ресурс]. — URL: https://peps.python.org/pep-0008/ (дата обращения: 14.03.2026).
```

- The quoted title goes inside «», followed by `[Электронный ресурс]`, the URL and the access date. Put only the resource's own name there: author, journal, year or pages would land inside the «» as well. Bibliographic fields for online articles are not supported yet, except on the sites below.
- Only `http(s)` links become sources. Citations are collected from the start of the document up to the first heading containing `Заключение`. Anything from that heading on stays a plain link. Citing in the conclusion is not recommended.
- **Sources without a URL** (printed laws, monographs) are not supported by MGost yet. Write them by hand as a numbered list in the sources section, before `sources(N)` where `N` is the next number, and cite them as plain `[1]`…`[N-1]` in the text. Everything that has a URL still goes through `[[key]](url)`, laws on consultant.ru included.

```md
# **Список использованных источников
1. Гражданский кодекс Российской Федерации (часть первая) : Федеральный закон от 30.11.1994 № 51-ФЗ // Собрание законодательства РФ. – 1994. – № 32. – Ст. 3301.
`sources(2)`
```

Some sites have their own entry format. The site is matched by domain, a leading `www.` is ignored:

| Site | Entry |
| --- | --- |
| `arxiv.org` | the quoted title is ignored, the metadata is fetched: `Авторы. Название — arXiv, 2018.` |
| `consultant.ru` | `Название // КонсультантПлюс : справочно-правовая система. — URL: … (дата обращения: …).` |

- consultant.ru: the title comes from the page `<title>` without the trailing `\ КонсультантПлюс`, or from the quotes without a fetch. It is printed without «». Cite a law or code by its consultant.ru URL: `[[ГК]](https://www.consultant.ru/document/cons_doc_LAW_5142/)`. An article has its own URL and becomes a separate entry; to point at an article of a code already in the list, name it in the sentence.

## Macros

### Syntax

```md
`name`
`name: value`
`name(arg1, arg2)`
`name(arg1, arg2): value`
```

- A macro is inline code. One macro, one line: no line breaks inside the backticks.
- The name is case-insensitive. Arguments are split on commas and trimmed at the edges; spaces inside are kept.
- The value is everything after the first `: `.
- MGost has no inline code formatting. Inline code that is not a known macro is reduced to its name with a warning: `` `foo: bar` `` prints `foo`.
- Block macros use a fence whose language is the macro name, with the body as the value.
- A refused macro (missing permission, see [Permissions](#permissions)) is dropped with a warning; the build continues.

### When macros run

- **While parsing**: during DOM creation, before numbering. Can create DOM elements: variables, media, included files.
- **While writing**: during the DOM → `python-docx` transfer. Sees the final numbers, and affects only what is written after it.
- **After writing**: edits the finished `python-docx` document. Used by counters, which need the whole document.

### Reference

Each entry lists when it runs, the permissions it requires, optional permissions (needed only for some uses; without them the macro runs but skips that use), and the minimum trust on articha.ru.

#### build_graph
Runs: while parsing. Required: `FILE_READING`, `PASS_ARGUMENTS`, `TOOLS`. Optional: none. Trust: 75.

A figure rendered by Graphviz from [DOT](https://graphviz.org/doc/info/lang.html). The graph name is the caption.

````md
```build_graph
digraph "Поток данных" {
    rankdir=LR
    "Пользователь" -> "Сервис" -> "База данных"
}
```
````

#### color
Runs: while writing. Required: `PASS_ARGUMENTS`. Optional: none. Trust: 40.

Colors text. RGB, HEX or a [WD_COLOR_INDEX](https://python-docx.readthedocs.io/en/latest/api/enum/WdColorIndex.html) name. Unknown color: text uncolored, warning.

```md
`color(255,0,0): Красный` `color(#00FF00): Зелёный` `color(DARK_BLUE): Синий`
```

#### comment
Runs: while parsing. Required: none. Optional: none. Trust: 1.

Removed with its value. A note that stays in the source only.

```md
`comment: переписать абзац`
```

#### count_appendix
Runs: while writing, after writing. Required: none. Optional: none. Trust: 1.

Number of listings in the document.

#### count_formulas
Runs: while writing, after writing. Required: none. Optional: none. Trust: 1.

Number of formulas.

#### count_images
Runs: while writing, after writing. Required: none. Optional: none. Trust: 1.

Number of figures, `build_graph` included.

#### count_sources
Runs: while writing, after writing. Required: none. Optional: none. Trust: 1.

Number of sources produced by `sources`.

#### count_tables
Runs: while writing, after writing. Required: none. Optional: none. Trust: 1.

Number of tables.

```md
Работа содержит `count_images` рисунков, `count_tables` таблиц и `count_sources` источников.
```

#### formula
Runs: while parsing. Required: `ADD_VARIABLES`, `PASS_ARGUMENTS`. Optional: none. Trust: 40.

A numbered LaTeX formula, see [Formulas](#formulas). Exactly one argument (the name); empty LaTeX is an error.

#### formula_describe
Runs: while parsing. Required: `PASS_ARGUMENTS`. Optional: none. Trust: 40.

A ГОСТ-styled «где …» block, one line per argument. Not linked to any formula: place it after the formula whose symbols it names.

#### highlight_color
Runs: while writing. Required: `PASS_ARGUMENTS`. Optional: none. Trust: 40.

Text background. One `WD_COLOR_INDEX` name: `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`.

```md
`highlight_color(YELLOW): проверить`
```

#### include
Runs: while parsing. Required: `FILE_READING`. Optional: `NETWORK_ACCESS`. Trust: 75.

Inserts another file in place. `include: path` and `include(path)` are equivalent.

- `.md`/`.markdown`: parsed as if written here. Its headings are numbered and listed in the TOC; its relative paths keep working.
- `.txt`: plain paragraphs split on blank lines.
- `.docx`: the body is copied with its own styles, lists, tables, images and links, so it looks as it does in Word, not as ГОСТ. Headers, footers, footnotes, comments and charts are not carried over.
- `include(file.docx, section)` also keeps the file's page setup (margins, size, orientation): it becomes a section of its own, and the document continues on a new page with ГОСТ margins. This is how the title page and the assignment page are added. Without `section`, the `.docx` joins the current section, which suits a fragment such as a table.
- Write `include` on a line of its own. Inside a paragraph or a table it splits the text around it.
- `https://…` URL: downloaded once into the project (needs `NETWORK_ACCESS`). Two URLs ending in the same file name are refused.
- Paths are relative to the including file. Paths outside the document folder follow [Files and paths](#files-and-paths). Cycles and missing files give a warning.

#### listing
Runs: while parsing. Required: `ADD_VARIABLES`, `FILE_READING`, `PASS_ARGUMENTS`. Optional: none. Trust: 75.

A numbered code listing from a file, see [Listings](#listings). At most one argument (the caption).

#### mention
Runs: while writing. Required: `READ_VARIABLES`, `PASS_ARGUMENTS`. Optional: none. Trust: 40.

The number of a figure, table, formula or listing, see [Mentions](#mentions). Argument `only_number` drops the noun.

#### orientation
Runs: while parsing. Required: none. Optional: none. Trust: 1.

`orientation(landscape)` / `orientation(portrait)`. What follows starts on a new page in that orientation (no `page_break` needed). Margins keep the 30 mm binding edge; images fit the new page. At the very start of the document it changes the first page without a break. Repeating the current orientation is ignored.

#### page_break
Runs: while writing. Required: none. Optional: none. Trust: 1.

A page break. A service macro: avoid it, since `#` headings and `orientation` already start new pages. The one regular use is before each `## **Приложение …`.

#### print_plain_text
Runs: while writing, after writing. Required: `FILE_READING`, `PYTHON_EXECUTION`, `PASS_ARGUMENTS`, `TOOLS`. Optional: none. Trust: 100.

Runs a Python file and inserts its stdout in place. Each script is limited to about one second.

```md
Считаем: `print_plain_text: counter.py`
```

#### set_image_dpi
Runs: while writing. Required: `SETTINGS_CHANGE`, `PASS_ARGUMENTS`. Optional: none. Trust: 40.

Pixel density images are reduced to, integer 72–300, default 150. It does not change the size on the page. Affects images after it, so put it at the top. 150 suits screenshots and diagrams, 300 suits photos.

#### set_list_digit
Runs: while writing. Required: `SETTINGS_CHANGE`. Optional: `PASS_ARGUMENTS`. Trust: 40.

#### set_list_marker
Runs: while writing. Required: `SETTINGS_CHANGE`. Optional: `PASS_ARGUMENTS`. Trust: 40.

Change the formatting of the bulleted (`set_list_marker`) or numbered (`set_list_digit`) lists that follow. The defaults already follow ГОСТ, so use these only for a list that must deviate from it, and restore the defaults right after with a call without arguments.

Three arguments: the marker before the text, the ending of every item but the last, and the ending of the last item. `{counter}` in `set_list_digit` is the item number. Spaces at the edges of each argument are dropped, inner spaces are kept. A space and a tab after the marker or number are added automatically, so don't end the first argument with a space.

```md
`set_list_marker(-,;,.)`

- Igor
- Ivan

`set_list_marker`
```

#### sources
Runs: while parsing. Required: `READ_VARIABLES`. Optional: `PASS_ARGUMENTS`, `NETWORK_ACCESS`. Trust: 25.

The bibliography, see [Sources](#sources). `sources(N)` starts numbering at N. Without `NETWORK_ACCESS`, page titles are not fetched.

#### store_var
Runs: while parsing. Required: `ADD_VARIABLES`, `PASS_ARGUMENTS`. Optional: none. Trust: 40.

#### store_var_return
Runs: while parsing. Required: `ADD_VARIABLES`, `READ_VARIABLES`, `PASS_ARGUMENTS`. Optional: none. Trust: 40.

#### var
Runs: while parsing. Required: `READ_VARIABLES`, `PASS_ARGUMENTS`. Optional: none. Trust: 40.

Text variables. `store_var(name): text` stores silently, `store_var_return(name): text` stores and prints, `var(name)` prints. Use them for sentences repeated across the work (the goal, chapter summaries).

```md
Цель работы — `store_var_return(цель): разработать сервис учёта заявок`.
…
В работе удалось `var(цель)`.
```

#### table_name
Runs: while parsing. Required: `SETTINGS_CHANGE`, `PASS_ARGUMENTS`. Optional: none. Trust: 40.

Names the next table, see [Tables](#tables).

#### table_of_contents
Runs: while parsing. Required: `READ_VARIABLES`. Optional: none. Trust: 25.

The table of contents. Put it under `# **Содержание`. Page numbers are filled by Word: the user presses Ctrl+A, then F9, after opening.

#### today
Runs: while parsing. Required: `PASS_ARGUMENTS`, `EXPRESSION_EVALUATION`. Optional: none. Trust: 85.

Current date and time, the value is a Python [strftime](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior) format. Time zone is fixed to MSK (+03:00).

```md
`today: %d.%m.%Y`
```

#### todo
Runs: while parsing. Required: `PASS_ARGUMENTS`. Optional: none. Trust: 40.

Removed from the document; the value shows up in the build log. Written `TODO` (any case).

```md
`TODO: добавить расчёт надёжности`
```

#### work_interval
Runs: while writing. Required: `EDIT_VARIABLES`, `PASS_ARGUMENTS`. Optional: none. Trust: 40.

The period the work was written in, used for automatic dates (source access dates). One argument: start date, end is today. Two: start and end. Default: the last week.

Accepted dates: `DD.MM.YYYY` (`1.2.2026` too), `YYYY.MM.DD`, `DD-MM-YYYY`, `DD.MM` (current year), ISO 8601 (`2026-02-01`, `2026-02-01T00:00:00+03:00`), and a Unix timestamp. `MM/DD/YYYY` is not accepted.

```md
`work_interval(01.02.2026, 30.05.2026)`
```

## Permissions

Every build has a permission grant. A macro whose required permissions are not all granted is dropped with a warning; optional ones only disable part of the macro.

| Permission | Allows |
|---|---|
| `READ_VARIABLES` | reading variables and media names |
| `ADD_VARIABLES` | creating variables and named media |
| `EDIT_VARIABLES` | changing build-wide values |
| `PASS_ARGUMENTS` | passing arguments to macros |
| `SETTINGS_CHANGE` | changing list, image and table settings |
| `NETWORK_ACCESS` | downloading includes and source titles |
| `FILE_READING` | reading files of the project |
| `TOOLS` | running external programs (Graphviz) |
| `EXPRESSION_EVALUATION` | evaluating expressions |
| `PYTHON_EXECUTION` | running the author's Python |

On articha.ru the grant follows the user's [trust level](https://articha.ru/auth/trust). Each threshold adds permissions to the ones below it:

| Trust | Adds |
|---|---|
| 1 | nothing (macros requiring no permissions) |
| 25 | `READ_VARIABLES` |
| 40 | `ADD_VARIABLES`, `EDIT_VARIABLES`, `PASS_ARGUMENTS`, `SETTINGS_CHANGE`, `NETWORK_ACCESS` |
| 75 | `FILE_READING`, `TOOLS` |
| 85 | `EXPRESSION_EVALUATION` |
| 100 | `PYTHON_EXECUTION` |

If a user's document loses macros with «не выданы необходимые права», their trust is too low for them: suggest raising trust, not rewriting the document.

## Files and paths

- Paths in images and macros are relative to the `.md` file that contains them.
- Absolute paths and paths leaving the folder (`C:/…`, `/home/…`, `../…`) work only with the CLI: it uploads those files with the project, and the server substitutes its copy at build time. On the site they appear under «Внешние файлы»: they can be edited and deleted there, but not moved or renamed.
- A file the document stops referencing is deleted from the server after the next successful build.

## Using MGost on articha.ru

- **Projects**: a folder of files (`.md`, images, code, included files) edited in the browser or synced from the CLI. The project has one root `.md` and one output `.docx`.
- **Fast conversion**: a single `.md` converted without a project.
- Both need an account. A user may have at most 2 builds queued or running.
- A build is stopped after 60 seconds. The usual cause is many sources whose titles have to be fetched (about one second each). Quoted titles avoid the fetch.

## MGost CLI

PyPI package [`mgost`](https://github.com/ArtichaTM/MGost) (Python 3.13), run through `uvx` with `@latest` so the client always matches the server. It syncs a local folder with a project on articha.ru and runs the build on the server.

```console
$ uvx -p 3.13 mgost@latest init     # first run asks for ARTICHAAPI_TOKEN, then creates or picks a project
$ uvx -p 3.13 mgost@latest sync     # sync without building
$ uvx -p 3.13 mgost@latest render   # sync, build on the server, download the .docx
```

Run `mgost sync` first and read its output, then `mgost render`. Sync reports missing and external files, including those used by `include`d files, before any build is spent on them.

- The API token comes from https://articha.ru/auth/tokens/. It is read from the `ARTICHAAPI_TOKEN` environment variable or `.mgost/.env`.
- `.mgost/` in the project root holds the CLI settings. Every command accepts `--root/-r <folder>`.
- Sync transfers the root `.md`, the output `.docx`, and the files the server reports the document needs. Other files in the folder are not uploaded.
- Files used by an `include`d `.md` are discovered only after that `.md` is on the server, so after adding an include run `mgost sync` until it reports nothing new.
- The build log is printed to the console.

## Pitfalls

- Hand-typed numbers, captions or bibliography entries. Let MGost generate them.
- Fenced code that is not a macro: the content is lost.
- Duplicate media names: `mention` resolves the first one.
- Two `table_name` before one table: the first name is lost.
- `page_break` used for layout. It is a service macro; outside appendices, let headings place the pages.
- Citations at or after `# **Заключение` are not collected.
- Macros split across lines, or an unclosed backtick that swallows the text after it.
- LaTeX errors in `formula`: the formula is not produced.
- TOC page numbers show `-` until Word updates fields (Ctrl+A, F9).

## Complete example

A short work using most features. The [annotated example](https://articha.ru/mgost/user_docs/example/) explains it line by line.

````md
`include(title.docx, section)`

`work_interval(01.02.2026, 30.05.2026)`

# **Аннотация
Работа содержит `count_images` рисунка, `count_tables` таблицу, `count_formulas` формулу и `count_sources` источника.

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

# **Введение
Цель работы — `store_var_return(цель): разработать сервис учёта заявок`.

# Анализ предметной области
## Существующие решения
Популярность языков приведена на сайте [[TIOBE]](https://www.tiobe.com/tiobe-index/ "TIOBE Index").
Сравнение решений приведено в таблице `mention(only_number): Сравнение решений`.

`table_name: Сравнение решений`

| Решение | Цена |
|---------|------|
| Jira    | 10   |
| Trello  | 5    |

## Постановка задачи
Цель — `var(цель)`. Поток данных показан на `mention: Поток данных`.

```build_graph
digraph "Поток данных" {
    rankdir=LR
    "Пользователь" -> "Сервис" -> "База данных"
}
```

Нагрузка оценивается по формуле `mention(only_number): нагрузка`:

`formula(нагрузка): N=\frac{R}{t}`
`formula_describe(R — число запросов, t — время в секундах)`

# Реализация
## Структура проекта
Схема модулей представлена на `mention: Схема модулей`.

![Схема модулей](./img/modules.png)

Код сервиса приведён в листинге `mention(only_number): Сервис заявок`.
Он оформлен по рекомендациям [[PEP8]](https://peps.python.org/pep-0008/).

# **Заключение
Цель работы — `var(цель)` — достигнута.

# **Список использованных источников
`sources`

# **Приложения
Приложение А - Код сервиса

`page_break`

## **Приложение А - Код сервиса
`listing(Сервис заявок): ./code/service.py`
````