md2gost 1.5.1 → 1.6.0

package/README.md

@@ -113,14 +113,17 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 	* [Картинки](#картинки)
 	* [Листинг](#листинг)
 	* [Таблицы](#таблицы)
+	* [Формулы](#формулы)
 	* [Комментарии](#комментарии)
+	* [Блоки Admonition](#блоки-admonition)
 	* [Разрыв страницы](#разрыв-страницы)
 * Дополнительный синтаксис:
 	* [Правила (!!rule)](#правила)
 	* [Оглавление](#оглавление)
 	* [Разрыв раздела](#разрыв-раздела)
+	* [Колонтитулы](#колонтитулы)
 	* [Автонумерация](#автонумерация)
-	* [Вставка docx/pdf (вставка титульника)](#вставка-внешнего-документа)
+	* [Вставка DOCX, PDF и Markdown](#вставка-внешнего-документа)
 	* [Автозамены](#автозамены)
 * Переключаемые функции:
 	* [Подсветка синтаксиса кода](#подсветка-синтаксиса-кода)
@@ -239,19 +242,19 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 ![демонстрация разницы переносов строк](https://raw.githubusercontent.com/MixelTe/md2gost/master/imgs/screenshot_linebreaks.png)
 
 Выделение с помощью обратных кавычек ``` `монотекст` ``` по умолчанию отображается как курсив. С помощью [правила](#правила) `backtick_mono` можно изменить отображение:
-* `!!rule backtick_mono italic` - курсив (по умолчанию)
+* `!!rule backtick_mono italic` – курсив (по умолчанию)
 
 	![backtick_mono italic](https://raw.githubusercontent.com/MixelTe/md2gost/master/imgs/backtick_mono_italic.png)
 
-* `!!rule backtick_mono off` - обычный текст
+* `!!rule backtick_mono off` – обычный текст
 
 	![backtick_mono off](https://raw.githubusercontent.com/MixelTe/md2gost/master/imgs/backtick_mono_off.png)
 
-* `!!rule backtick_mono on` - моношрифт
+* `!!rule backtick_mono on` – моношрифт
 
 	![backtick_mono on](https://raw.githubusercontent.com/MixelTe/md2gost/master/imgs/backtick_mono_on.png)
 
-* `!!rule backtick_mono outline` - моношрифт в рамочке
+* `!!rule backtick_mono outline` – моношрифт в рамочке
 
 	![backtick_mono outline](https://raw.githubusercontent.com/MixelTe/md2gost/master/imgs/backtick_mono_outline.png)
 
@@ -302,6 +305,8 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 ![Рисунок 1.5 - Важные зарисовки, с очень длинным названием, <br>которое не умещается в одну строку] (image.png){340}
 ```
 
+Если курсор находится на строке с Markdown-картинкой, при вставке изображения из буфера обмена доступно действие **Replace image with …**. Оно сохраняет изображение в той же папке под новым именем с номером (например, `image.png` → `image1.png`) и обновляет путь в Markdown. Исходный файл не перезаписывается. Работает с локальными путями в сохранённом файле.
+
 
 ### Листинг
 В отличие от обычного Markdown после кода языка в первой строке пишется заголовок листинга (при разрыве листинга на несколько страниц заголовок продублируется автоматически).
@@ -353,6 +358,29 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 | текст |   текст   |  текст |
 ```
 
+### Формулы
+
+Формулы записываются в LaTeX-синтаксис. Строчные формулы заключаются в одинарные знаки доллара, а блочные — в двойные. Открывающий и закрывающий маркеры блочной формулы должны находиться на отдельных строках; формулы внутри абзаца при экспорте не считаются блочными. Чтобы вывести знак доллара как обычный символ, экранируйте его обратным слешем: `\$`.
+
+```md
+Скорость равна $v = \frac{s}{t}$.
+
+$$
+E = mc^2
+$$
+```
+
+Чтобы указать номер блочной формуле напишите любой текст в круглых скобках на отдельной строке непосредственно перед формулой:
+
+```md
+(А.1)
+$$
+E = mc^2
+$$
+
+Как показано в формуле А.1, энергия зависит от массы.
+```
+
 ### Комментарии
 Этот текст исчезнет при экспорте. Поддерживаются только отдельно стоящие комментарии.
 ```md
@@ -363,6 +391,88 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 <!-- Исчезнет вся строка --> это тоже исчезнет
 ```
 
+### Блоки Admonition
+
+Admonition – это выделенный информационный блок. Синтаксис совместим с [Admonitions в Docusaurus](https://docusaurus.io/docs/markdown-features/admonitions): блок начинается с трёх двоеточий и его типа, а заканчивается строкой из трёх двоеточий.
+
+> **Важно:** Admonition не является элементом оформления по ГОСТ. Используйте его в документах, где важнее наглядно отделить примечание, рекомендацию или предупреждение, чем строго следовать ГОСТ.
+
+Поддерживаются типы `note`, `info`, `tip`, `warning` и `danger`. У каждого типа свой цвет; при стандартных настройках это соответственно нейтральный, синий, зелёный, оранжевый и красный блок.
+
+````md
+:::note
+Обычное примечание. Внутри работает Markdown: **жирный текст**, *курсив* и [ссылки](https://example.com).
+:::
+
+:::info
+В процессе измерения допускается отклонение температуры не более чем на 2 °C от заданного значения.
+:::
+
+:::tip
+Для повышения точности измерений выполняйте калибровку прибора перед каждой серией экспериментов.
+:::
+
+:::warning
+Перед запуском алгоритма убедитесь, что входные данные приведены к единому масштабу.
+:::
+
+:::danger
+Удаление исходных данных до завершения обработки делает результаты эксперимента невосстановимыми.
+:::
+````
+
+![Примеры оформления информационных блоков разных типов](imgs/admonition.png)
+
+Заголовок блока можно заменить своим текстом, указав его в квадратных скобках, можно указать пустой заголовок. Некоторые форматтеры Markdown требуют пустые строки внутри блока, поэтому для них используйте такой вариант. Форматтер, идущий вместе с расширением, понимает Admonition и без пустых строк.
+
+````md
+:::tip[Рекомендация по *измерениям*]
+
+Перед каждой серией измерений выполняйте калибровку прибора.
+
+:::
+:::note[]
+Без заголовка
+:::
+:::note[ ]
+Без заголовка, но с иконкой
+:::
+````
+
+![Примеры отрендеренных информационных блоков с различными заголовками и иконками](imgs/admonition2.png)
+
+#### Настройка оформления
+
+Оформление меняется правилами `!!rule`. Вместо `<type>` укажите один из типов блока или `all`, чтобы применить правило ко всем Admonition; правило для конкретного типа, указанное позднее, имеет приоритет.
+
+Правило `title` используется, только когда заголовок не указан в квадратных скобках у самого блока, можно указать пустое значение чтобы убрать заголовок (укажите `&nbsp;` чтобы сохранить иконку с пустым заголовком).
+
+| Что настраивается                                       | Правило                                                    | Пример                                         |
+|---------------------------------------------------------|------------------------------------------------------------|------------------------------------------------|
+| Внешний отступ до/после блока, пт                       | `!!rule admonition <type> spacing <before\|after> <int>`   | `!!rule admonition all spacing before 8`       |
+| Отступ блока слева, см                                  | `!!rule admonition <type> indent <float>`                  | `!!rule admonition all indent 1.25`            |
+| Внутренние отступы блока по горизонтали и вертикали, пт | `!!rule admonition <type> padding <horizontal> <vertical>` | `!!rule admonition all padding 10 6`           |
+| Цвет фона                                               | `!!rule admonition <type> background <#RRGGBB>`            | `!!rule admonition warning background #FFF6E8` |
+| Акцентный цвет: полоска, заголовок и иконка             | `!!rule admonition <type> color <#RRGGBB>`                 | `!!rule admonition warning color #B26A00`      |
+| Ширина цветной полоски слева, пт                        | `!!rule admonition <type> bar_width <float>`               | `!!rule admonition all bar_width 2.25`         |
+| Показывать иконку возле заголовка                       | `!!rule admonition <type> icon <on\|off>`                  | `!!rule admonition note icon off`              |
+| Размер иконки, пт                                       | `!!rule admonition <type> icon size <int>`                 | `!!rule admonition all icon size 16`           |
+| Окрашивать заголовок акцентным цветом                   | `!!rule admonition <type> title_color <on\|off>`           | `!!rule admonition all title_color off`        |
+| Заголовок по умолчанию                                  | `!!rule admonition <type> title <текст>`                   | `!!rule admonition warning title **Важно**`    |
+
+Например, следующий набор правил создаёт блоки в строгом стиле, а для критического сообщения задаёт более заметный цвет:
+
+```
+!!rule admonition all padding 6 4
+!!rule admonition all icon off
+!!rule admonition all title_color off
+!!rule admonition all background #ffffff
+!!rule admonition danger background #FFF4F4
+!!rule admonition danger icon on
+```
+
+![Примеры блоков с измененными правилами оформления](imgs/admonition3.png)
+
 ### Разрыв страницы
 ```
 ---
@@ -372,7 +482,7 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 
 
 ### Правила
-Правила - специальные команды для изменения работы системы. Их можно писать в любом месте документа - они влияют на весь документ вне зависимости от расположения. Если одно и тоже правило указано несколько раз, используется последнее значение.
+Правила – специальные команды для изменения работы системы. Их можно писать в любом месте документа – они влияют на весь документ вне зависимости от расположения. Если одно и тоже правило указано несколько раз, используется последнее значение.
 
 ```
 !!rule имя правила
@@ -426,8 +536,46 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 Альбомная ориентация с нумерацией с 3-й страницы
 ```
 
+### Колонтитулы
+
+Колонтитулы позволяют выводить повторяющуюся информацию сверху и снизу страниц: например, инвентарный номер документа и таблицу для регистрации изменений. Синтаксис поддерживает текст и одну таблицу внутри каждого блока.
+
+```md
+!!header align=center
+Инвентарный номер:<br>567.0004653-03 98 01-07
+!!endheader
+
+!!footer
+| № изменения: _________ | Подпись отв. лица: __________ | Стр. [!page] из [!pages] |
+|:--|:--|--:|
+!!endfooter
+```
+
+**Синтаксис:**
+
+```text
+!!header [align=left|center|right]
+содержимое
+!!endheader
+
+!!footer [align=left|center|right]
+содержимое
+!!endfooter
+
+!!header none
+!!footer none|auto
+```
+
+- `align` задаёт выравнивание текстового содержимого; по умолчанию – `left`.
+- В блоке допустимы обычный текст, inline-форматирование и одна Markdown-таблица. Таблица занимает всю рабочую ширину страницы и выводится с границами.
+- `[!page]` – номер текущей страницы; `[!pages]` – общее число страниц документа.
+- `!!header` и `!!footer` настраивают текущий раздел и не создают разрыв раздела. За создание раздела отвечает только `!!section`.
+- Настройка действует для текущего и следующих разделов до следующего одноимённого оператора или конца документа. Новый `!!header` не изменяет footer и наоборот.
+- `!!header none` и `!!footer none` отключают соответствующий колонтитул. `!!footer auto` возвращает стандартный автоматический нижний колонтитул с номером страницы.
+- Чтобы первая страница имела иной колонтитул, перед ней следует создать отдельный раздел с помощью `!!section`.
+
 ### Автонумерация
-Система автонумерации автоматически нумерует элементы документа (разделы, рисунки, таблицы, листинги, источники) и позволяет ссылаться на них из текста.
+Система автонумерации автоматически нумерует элементы документа (разделы, рисунки, таблицы, листинги, формулы, источники) и позволяет ссылаться на них из текста.
 
 Номера элементов и ссылки задаются выражениями в квадратных скобках: `[...]`.
 
@@ -435,7 +583,7 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 
 #### Базовый функционал:
 
-В тексте `[#]` указывает на следующий элемент нумерации - рисунок, таблица, листинг - первое, что из этого встретилось.
+В тексте `[#]` указывает на следующий элемент нумерации – рисунок, таблица, листинг, формула – первое, что из этого встретилось.
 
 В подписи элемента `[#]` заменяется на номер и подпись (например: `Рисунок 1 - `).
 
@@ -466,6 +614,14 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 Заголовок 1 | Заголовок 2
 ------------|------------
 текст       | текст
+
+## [#] Пример с формулой
+В формуле [#] показана связь энергии и массы.
+
+[#]
+$$
+E = mc^2
+$$
 ````
 
 **Результат:**
@@ -492,6 +648,11 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 Заголовок 1 | Заголовок 2
 ------------|------------
 текст       | текст
+
+## 1.4 Пример с формулой
+В формуле 1 показана связь энергии и массы.
+
+E = mc^2 \qquad (1)
 ````
 
 *У картинки перед круглой скобкой пробела быть не должно (тут он стоит из-за некоторых проблем с отображением этого файла)*
@@ -573,6 +734,12 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 ![[cat] Кот] (cat1.png)
 ![[img2] Котик] (cat2.png)
 ![[Котяра] Котяра] (cat3.png)
+
+[energy]
+$$
+E = mc^2
+$$
+Как показано в формуле [energy], энергия кота зависит от массы.
 ```
 
 К именованной ссылке также можно применять смещение: `[name ± N]`.
@@ -592,14 +759,16 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 Документ содержит [!pages] страниц,
 [!imgs] рисунков,
 [!tables] таблиц,
-[!codes] листингов.
+[!codes] листингов,
+[!formulas] формул,
+[!sources] источников.
 ```
 
 **Примечание:** `[!pages]` может отображаться некоректно до рендера в pdf (как пустота или неверное значение). В таком случае выделите это место в Word и нажмите ПКМ->"Обновить поле" (при рендере в pdf не требуется).
 
 #### Настройки автонумерации
 * Включить ленивую автонумерацию: `!!rule numbering lazy`
-	* Когда включено, более не нужно писать `[#]` в названиях картинок, таблиц и т.д. - добавляется автоматически
+	* Когда включено, более не нужно писать `[#]` в названиях картинок, таблиц и т.д. – добавляется автоматически
 * Включить нумерацию по разделам: `!!rule numbering sections`
 	* `Рисунок 1 - Кот` -> `Рисунок 1.1 - Кот`
 * Отключить автоматическое добавление названия элемента: `!!rule numbering autoprefix off`
@@ -628,24 +797,36 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 ```html Шаблон html страницы
 <html></html>
 ```
+
+В формуле [#] показана связь энергии и массы.
+
+$$
+E = mc^2
+$$
 ````
 
 
 ### Вставка внешнего документа
 
-Команда позволяет вставить содержимое файлов DOCX (с поддержкой шаблонизации) или PDF. Путь к документу вычисляется относителено `.g.md` файла
+Команда позволяет вставить содержимое файлов DOCX, PDF, `.md` и `.g.md`.
 
 Синтаксис: `!!(путь/к/файлу){"ключ": "значение"}`
 
 
-**Особенности вставки:**
-* **DOCX:** Поддерживает передачу параметров. Внутри файла поля должны быть оформлены в двойных фигурных скобках: `{{поле}}`.
+Тип вставки определяется расширением файла:
+* **DOCX:** Поддерживает передачу параметров. Поля внутри документа оформляются в двойных фигурных скобках: `{{поле}}`.
 
 	![screenshot](https://raw.githubusercontent.com/MixelTe/md2gost/master/imgs/screenshot_doc_include.png)
 
-* **PDF:** Вставляется «как есть», блок параметров должен быть пустым `{}`.
+* **PDF:** Вставляется «как есть». Блок параметров должен быть пустым `{}`.
+
+* **Markdown (`.md`, `.g.md`):** содержимое файла раскрывается непосредственно в тело документа до рендера. Поэтому внутри подключаемого файла можно использовать обычный синтаксис md2gost, включая правила, секции и другие вставки.
 
-> **Ограничение:** Вставка внешнего файла поддерживается только при экспорте в PDF.
+	Подробнее о передаче переменных, вложенных Markdown-вставках и шаблонизации см. в разделе [Markdown-вставки и шаблонизация](#markdown-вставки-и-шаблонизация).
+
+Путь к подключаемому файлу вычисляется относительно файла, содержащего директиву вставки.
+
+> **Ограничение DOCX/PDF:** такие вставки добавляются только при экспорте в PDF. Markdown-вставки работают при экспорте и в DOCX, и в PDF.
 
 
 #### Примеры использования
@@ -670,6 +851,8 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 !!section from 2
 ```
 
+В подключаемом DOCX эти значения можно использовать как `{{taskN}}`, `{{topic}}`, `{{group}}` и `{{name}}`.
+
 Подробнее про `!!section` в главе [Разрыв раздела](#разрыв-раздела).
 
 **3. Вставка в произвольное место документа**
@@ -723,17 +906,21 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 - `&Tab;` на отступ (таб)
 - `&Star;` на `*`
 - `&#124;` на `|`
+- `&amp;` на `&`
 - `&shy;` на Soft Hyphen (мягкий перенос)
 - `&#x200B;` на ничего (используйте чтобы обмануть парсер)
 - `&alpha; &beta; &gamma; &delta; &epsilon; &zeta; &eta; &theta; &iota; &kappa; &lambda; &mu; &nu; &xi; &omicron; &pi; &rho; &sigma; &tau; &upsilon; &phi; &chi; &psi; &omega; &Delta; &Sigma; &Omega;` на `α β γ δ ε ζ η θ ι κ λ μ ν ξ ο π ρ σ τ υ φ χ ψ ω Δ Σ Ω`
 - `&infin; &sum; &prod; &radic; &int; &part; &asymp; &ne; &lt; &gt; &le; &ge; &plusmn; &times; &divide;` на `∞ ∑ ∏ √ ∫ ∂ ≈ ≠ < > ≤ ≥ ± × ÷`
 - `&copy; &reg; &trade; &sect; &para; &hellip; &bull; &middot; &deg; &euro; &pound; &yen; &cent; &curren; &fnof; &permil;` на `© ® ™ § ¶ … • · ° € £ ¥ ¢ ¤ ƒ ‰`
+- `[!page]` на номер текущей страницы
 - `[!pages]` на кол-во страниц
 - `[!imgs]` на кол-во картинок
 - `[!tables]` на кол-во таблиц
 - `[!codes]` на кол-во листингов
 - `[!sources]` на кол-во источников
 
+При экспорте обычные пробелы автоматически заменяются на неразрывные там, где части записи должны оставаться вместе: после коротких служебных слов (`в таблице`), между обозначением и номером (`рисунок 1`, `№ 5`, `ГОСТ 123`), в инициалах (`А. С. Пушкин`), адресах (`ул. Ленина`), датах (`2026 г.`), а также между числом и единицей измерения (`15 кг`, `25 %`). Дефисы внутри слов и обозначений (`веб-сервис`, `UTF-8`) также становятся неразрывными. Исходный Markdown при этом не меняется.
+
 ### Настройка стилей
 Строгость ГОСТа не уступает его разнообразию. В этом разделе представлены правила для настройки стилей.
 
@@ -759,6 +946,9 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 		- `!!rule text spacing after <int>`
 		- Пример: `!!rule text spacing after 0`
 		- По умолчанию: `8` пт
+* Автоматическая расстановка переносов
+	- `!!rule hyphenation`
+	- По умолчанию: выключено
 * Заголовки
 	* Размер заголовка
 		- `!!rule headings h<1-6>[+] size <int>`
@@ -792,9 +982,6 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 			!!rule headings h2 size 16
 			!!rule headings h2+ spacing before 15
 			```
-* Автоматическая расстановка переносов
-	- `!!rule hyphenation`
-	- По умолчанию: выключено
 * Таблицы
 	* Начертание названия
 		- `!!rule table title style <normal|bold|italic>`
@@ -880,7 +1067,15 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 		- `!!rule list autopunctuation <on|off>`
 		- Пример: `!!rule list autopunctuation off`
 		- По умолчанию: `on`
-
+* Формулы
+	* Интервал перед формулой
+		- `!!rule formula spacing before <int>`
+		- Пример: `!!rule formula spacing before 6`
+		- По умолчанию: `0` пт
+	* Интервал после формулы
+		- `!!rule formula spacing after <int>`
+		- Пример: `!!rule formula spacing after 6`
+		- По умолчанию: наследуется от текста
 
 #### Примеры
 
@@ -950,3 +1145,207 @@ Without Microsoft Word, PDF export and several advanced Word-specific features a
 	- По умолчанию: время рендера
 * `!!rule rainbow`
 
+### Markdown-вставки и шаблонизация
+
+Markdown-файлы с расширением `.md` и `.g.md` обрабатываются иначе, чем DOCX и PDF: их содержимое раскрывается в исходный документ **до рендера** и становится его полноценной частью.
+
+Это позволяет разбивать большие документы на отдельные файлы и использовать повторно отдельные главы, таблицы, блоки и другие фрагменты.
+
+Например:
+
+```markdown
+# Отчёт
+
+!!(blocks/introduction.md){}
+
+!!(blocks/results.md){}
+```
+
+В подключаемых файлах разрешён весь синтаксис md2gost, включая:
+
+* правила форматирования;
+* секции;
+* изображения и ссылки;
+* другие Markdown-вставки.
+
+Относительные пути внутри подключаемого Markdown-файла вычисляются относительно самого подключаемого файла. Пути к изображениям и ссылкам при раскрытии вставки корректируются автоматически.
+
+
+#### Передача переменных
+
+В Markdown-вставку можно передавать переменные через блок параметров:
+
+```markdown
+!!(blocks/student.md){
+    "name": "Иванов И.И.",
+    "group": "КЛМН-01"
+}
+```
+
+В `blocks/student.md` они доступны через двойные фигурные скобки:
+
+```markdown
+# {{name}}
+
+Группа: {{group}}
+```
+
+Можно обращаться и к вложенным значениям:
+
+```markdown
+# {{student.name}}
+
+Группа: {{student.group}}
+Первый результат: {{student.scores[0]}}
+```
+
+Например:
+
+```markdown
+!!(blocks/student.md){
+    "student": {
+        "name": "Иванов И.И.",
+        "group": "КЛМН-01",
+        "scores": [5, 4, 5]
+    }
+}
+```
+
+
+#### Значения по умолчанию
+
+Для переменных можно указывать запасное значение:
+
+```markdown
+{{name || "Без имени"}}
+{{comment ?? "Комментарий отсутствует"}}
+```
+
+Поддерживаются два оператора:
+
+* `value || fallback` — использует запасное значение, если исходное значение отсутствует, равно `null`, `false`, `0` или пустой строке.
+* `value ?? fallback` — использует запасное значение только если исходное значение отсутствует или равно `null`.
+
+Для экранирования кавычки используется обратный слеш:
+
+```markdown
+{{name || "это \"инкогнито\" с обратным \\ слешом"}}
+```
+
+
+#### Передача объектов и массивов
+
+По умолчанию значение, подставляемое внутрь текста, преобразуется в строку.
+
+Если объект или массив нужно передать дальше во вложенную Markdown-вставку без такого преобразования, значение должно состоять только из одной переменной:
+
+```markdown
+!!(table.md){
+    "rows": "{{student.rows}}"
+}
+```
+
+В этом случае `rows` получит исходное значение `student.rows`, например массив или объект, а не его строковое представление.
+
+
+#### Наследование переменных
+
+Вложенная Markdown-вставка наследует переменные родительского документа.
+
+Например, если в основном документе доступна переменная `author`, она будет доступна и внутри подключаемого Markdown-файла без явной повторной передачи.
+
+При необходимости значение можно переопределить:
+
+```
+!!(chapter.md){
+    "author": "Петров П.П."
+}
+```
+
+Внутри `chapter.md` будет использовано новое значение `author`, а остальные переменные продолжат наследоваться от родителя.
+
+
+#### Неизвестные переменные и экранирование
+
+Если указанная переменная не существует, md2gost выводит предупреждение, а маркер остаётся в тексте без изменений:
+
+```
+{{unknownVariable}}
+```
+
+Чтобы вывести конструкцию `{{...}}` буквально и не выполнять подстановку, перед ней нужно поставить обратный слеш:
+
+```
+\{{name}}
+```
+
+Поддерживаются также HTML-комментарии:
+
+```
+<!-- Этот текст не попадёт в результат -->
+```
+
+Если последовательность `<!--` нужно вывести буквально, не создавая HTML-комментарий, её можно записать через шаблонную вставку:
+
+```
+{{"<!--"}}
+```
+
+
+#### Переменные главного документа
+
+При использовании npm-пакета переменные можно передать не только во вставку, но и непосредственно в главный документ через `MDRenderConfig.variables`:
+
+```ts
+await renderMarkdown({
+    input: "./report.g.md",
+    variables: {
+        author: "Иванов И.И.",
+        settings: { compact: true }
+    }
+});
+```
+
+После этого переменные доступны в основном документе и наследуются подключаемыми Markdown-файлами.
+
+
+#### Расширенная шаблонизация
+
+В подключаемых Markdown-файлах можно использовать условные блоки и циклы. В основном документе шаблонные выражения выполняются, если переменные переданы через `MDRenderConfig.variables` в программном API.
+
+```markdown
+{{#if showResults}}
+## Результаты
+{{#for result, index in results}}
+{{index + 1}}. {{result}}
+{{:else}}
+Результатов пока нет.
+{{/for}}
+{{:else}}
+Раздел скрыт.
+{{/if}}
+```
+
+Условие `{{#if ...}}` проверяет значение переменной или сравнение, например `{{#if score >= 5}}`. Цикл `{{#for value in items}}` перебирает массив; запись `{{#for value, key in items}}` дополнительно даёт индекс или ключ. Циклы также принимают объект, строку или целое число (повторение заданное число раз). Блок `{{:else}}` необязателен и работает как с условием, так и с пустым циклом. Блоки можно вкладывать друг в друга.
+
+В подстановках доступны значения переменных, строки, числа, `true`, `false`, `null` и одно бинарное действие. Поддерживаются арифметические операторы `+`, `-`, `*`, `/`, `//` (целочисленное деление), `%`, `**`; в условиях — сравнения `==`, `!=`, `<`, `<=`, `>`, `>=`, `in` и логические `and`, `or`, `&&`, `||`, `??`. Для подстановки по-прежнему работают `||` и `??` со значением по умолчанию.
+
+Чтобы убрать пробельные символы вокруг выражения, добавьте `-` после открывающих или перед закрывающими скобками: `{{- name -}}`. Для Markdown-вставки на отдельной строке форма `!!(-chapter.md-){}` убирает пробелы вокруг директивы. Запись `!!(--chapter.md--){}` убирает пробелы не только вокруг директивы, но и крайние внутри вставляемого документа. (Можно убирать пробелы только с одной стороны: `{{- name }}`, `!!(chapter.md-){}`)
+
+Для сложных или полученных извне шаблонов можно ограничить объём обработки через `MDRenderConfig.templateOptions`:
+
+```ts
+await renderMarkdown({
+    input: "./report.g.md",
+    variables: { showResults: true, results: ["Первый", "Второй"] },
+    templateOptions: {
+        allowLoops: true,
+        allowIncludes: true,
+        maxTotalIterations: 2000,
+        maxIncludeDepth: 100
+    }
+});
+```
+
+Также доступны ограничения `maxLoopIterations`, `maxDepth`, `maxIncludes`, `maxFileLength`, `maxTotalInputLength` и `maxGeneratedLength`. В расширении VS Code суммарное число итераций и глубина Markdown-вставок задаются настройками `md2gost.render.maxTotalIterations` и `md2gost.render.maxIncludeDepth`.
+