# Синтаксис Markdown (диалект md2gost)

Обычный Markdown описывает структуру текста. Для отчёта по ГОСТ нужны ещё: спецразделы без номера, подписи объектов, перекрёстные ссылки, библиография в заданном виде. **md2gost** расширяет MD ровно этими элементами; конвертер сам нумерует рисунки/таблицы/листинги и оформляет DOCX.

## Что совпадает с обычным MD

- Заголовки `#` … `######`
- Абзацы, **жирный**, *курсив*
- Маркированные и нумерованные списки
- Таблицы `| … |`
- Картинки `![alt](path.png)`
- Блоки кода в ограде ` ```язык `
- Формулы `$$ … $$` (и инлайн `$…$` где поддерживается)

## Зачем расширения

| Задача | Обычный MD | md2gost |
|--------|------------|---------|
| Введение без номера «1» | `# Введение` → станет разделом 1 | `# *ВВЕДЕНИЕ` |
| Подпись «Рисунок 1.1 — …» | руками / HTML | `%id` или title у картинки |
| «см. рис. 2» в тексте | нет семантики | `@Рисунок:id` |
| UML → картинка в Word | экспорт PNG вручную | fence `` ```uml `` / схема → Рисунок |

## Спецразделы

Звёздочка `*` = без автоматической нумерации раздела. Текст — ПРОПИСНЫМИ:

```markdown
# *СОДЕРЖАНИЕ
[TOC]

# *ВВЕДЕНИЕ

# 1 Название первого раздела
## 1.1 Подраздел

# *ЗАКЛЮЧЕНИЕ

# *СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ

# *ПРИЛОЖЕНИЯ
```

- После `# *СОДЕРЖАНИЕ` обязателен `[TOC]`.
- В конце названия заголовка точку не ставить.
- Для `PIS_custom` структура другая (практические работы) — см. [types.md](types.md).

## Рисунок (файл)

```markdown
Текст со ссылкой на @Рисунок:arch.

![описание](images/arch.png "%arch Название рисунка")
```

В тексте пишите **«Рисунок»**, не «рис.» / «рис».

## Таблица

```markdown
См. @Таблица:cmp.

%cmp Название таблицы

| A | B |
|---|---|
| 1 | 2 |
```

Склеивание ячеек:

- `^` — rowspan (продолжение ячейки сверху)
- `>` — colspan (продолжение слева)

Не ставить `^`/`>` в заголовочной строке; `>` — не в первом столбце. Графу «№ п/п» не добавлять.

## Листинг

~~~markdown
Фрагмент в @Листинг:code1.

%code1 Название листинга

```python
def f():
    return 1
```
~~~

## Диаграмма → Рисунок

Перед блоком — `%id Подпись`. Языки: `uml`, `plantuml`, `mermaid`/`mmd`, `idef0`, `dfd`/`data-flow-diagram` (Graphviz вшитый/PATH или Kroki), или id схемы (`c4`, `usecase`, …).

- `+listing` — ещё и Листинг с исходником
- `+landscape` — альбомная страница под широкий рисунок/таблицу

Подробности: [schemes.md](schemes.md).

## Формула

```markdown
%eq1
$$
E = mc^2
$$

Зависимость (@Формула:eq1) используется далее.
```

Нумеруются **только** формулы, на которые есть `@Формула:…`.

## Ссылки на объекты

`@Рисунок:id`, `@Таблица:id`, `@Листинг:id`, `@Формула:id` — id совпадает с меткой после `%` или в title картинки.

## Источники

В тексте: `[1]`, `[2, 3]` (для ВКР — `[1.5]`). В DOCX номера становятся ссылками на пункты списка источников.

В списке:

```markdown
[1]: Иванов И. И. Название. — М.: Наука, 2024. — 120 с.
```

Во **ВВЕДЕНИИ** и **ЗАКЛЮЧЕНИИ** ссылок `[n]` быть не должно.

## Приложения

```markdown
# *ПРИЛОЖЕНИЯ

## Приложение А Листинг модуля

…

## Приложение Б Графический материал
```

Буквы: А, Б, В, Г, Д, Е, Ж, И, К… **Нельзя:** Ё, З, Й, О, Ч, Ь, Ы, Ъ.

## Тире и разрыв страницы

- Тире в предложениях: «—» (по умолчанию сохраняется). Замена на «-»: `--emdash-to-hyphen`.
- Строка `---` / `***` / `___` по умолчанию **игнорируется**. Разрыв страницы: `--hr-pagebreak` или галочка в GUI.

## Автотитульник (метаданные в MD)

В начале файла можно указать блок с оградой `title` (номер работы, год, оверрайды полей). Рядом с файлом — `info_conv.yaml` с институтом, кафедрой, дисциплиной и преподавателем. ФИО и группа студента задаются в GUI / CLI, не в yaml. Автогенерация титула **по умолчанию выкл.** — включите `--auto-title` или галочку «Автотитул».

Подробно: [title.md](title.md).

## Запрещено в отчёте

- «рис.», «табл.»
- графа «№ п/п»
- сноски `[^1]`
- формулы обычным текстом вместо `$$…$$`
- нумерация спецразделов (`# ВВЕДЕНИЕ` вместо `# *ВВЕДЕНИЕ`)