md_to_gost/docs/markdown.md

Синтаксис 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 / схема → Рисунок

Спецразделы

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

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

# *ВВЕДЕНИЕ

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

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

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

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

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

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

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

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

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

Таблица

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

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

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

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

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

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

Листинг

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

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

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

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

Перед блоком — %id Подпись. Языки: uml, plantuml, mermaid/mmd, или id схемы (c4, bpmn, …).

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

Подробности: schemes.md.

Формула

%eq1
$$
E = mc^2
$$

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

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

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

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

Источники

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

В списке:

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

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

Приложения

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

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

…

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

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

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

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

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

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