Igor20264
160 lines
6.0 KiB
Markdown
160 lines
6.0 KiB
Markdown
# Синтаксис Markdown (диалект md2gost)
|
||
|
||
Обычный Markdown описывает структуру текста. Для отчёта по ГОСТ нужны ещё: спецразделы без номера, подписи объектов, перекрёстные ссылки, библиография в заданном виде. **md2gost** расширяет MD ровно этими элементами; конвертер сам нумерует рисунки/таблицы/листинги и оформляет DOCX.
|
||
|
||
## Что совпадает с обычным MD
|
||
|
||
- Заголовки `#` … `######`
|
||
- Абзацы, **жирный**, *курсив*
|
||
- Маркированные и нумерованные списки
|
||
- Таблицы `| … |`
|
||
- Картинки ``
|
||
- Блоки кода в ограде ` ```язык `
|
||
- Формулы `$$ … $$` (и инлайн `$…$` где поддерживается)
|
||
|
||
## Зачем расширения
|
||
|
||
| Задача | Обычный 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.
|
||
|
||
|
||
```
|
||
|
||
В тексте пишите **«Рисунок»**, не «рис.» / «рис».
|
||
|
||
## Таблица
|
||
|
||
```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]`
|
||
- формулы обычным текстом вместо `$$…$$`
|
||
- нумерация спецразделов (`# ВВЕДЕНИЕ` вместо `# *ВВЕДЕНИЕ`)
|