Правила структуры Markdown для docxmd
Этот документ — контракт между автором markdown и конвертером docxmd.
Если markdown написан по этим правилам, на выходе получится .docx,
оформленный по ГОСТ 7.32 (поля 30/15/20/20 мм, Times New Roman 12,
полуторный интервал, красная строка 1.25 см, заголовки структурных
элементов по центру в UPPERCASE, нумерованные разделы — с абзацного
отступа и сквозной нумерацией 1, 1.1, 1.1.1, ...).
Этот файл оптимизирован для использования в качестве system-промпта /
custom instructions у нейросети: можно скопировать целиком.
Структура папки
my_doc/
├── document.md # имя любое, но .md ровно один
└── media/ # опционально
├── image1.png
└── diagram.svg
- Папка должна содержать ровно один файл
.md (имя — любое).
- Изображения лежат в
media/ (или в любой другой подпапке — пути
ссылок резолвятся относительно папки с .md).
- Никаких других файлов конвертер не требует и не использует.
Заголовки
# Введение
## Анализ предметной области
### Существующие решения
#### Сравнительная таблица
# Заключение
Правила:
# (H1) — это заголовок структурного элемента в смысле ГОСТ 7.32 п. 6.3.3:
Реферат, Содержание, Введение, Заключение, Список использованных источников, Приложение А (и т. д.). В docx такие заголовки рендерятся
по центру, полностью прописными буквами (исходник можно писать
как обычно: # Введение → в docx будет ВВЕДЕНИЕ), 14 pt, жирный, без точки.
Не нумеруются. H1 может быть несколько на файл.- Сам заголовок документа (название отчёта) в markdown не пишется — он
оформляется на титульной странице Word и в зону ответственности
docxmd
не входит.
## (H2) — это раздел отчёта (первый уровень содержательной части).
В docx — с абзацного отступа 1,25 см, 12 pt, жирный, с автоматической
сквозной нумерацией: первый ## получит префикс 1, следующий — 2,
и так далее по всему документу. Структурные H1 счётчик не сбрасывают.###, ####, #####, ###### — подразделы, пункты, подпункты. Получают
номера вида 1.1, 1.1.1, 1.1.1.1, 1.1.1.1.1. Каскадный рестарт
работает: при новом ## нижние счётчики обнуляются.- Не пиши номера разделов вручную (
## 1.1 Описание) — Word нумерует
заголовки сам через multilevel-список. Ручной префикс даст двойную
нумерацию (1.1 1.1 Описание).
- Структура: H1 (структурные секции) → H2 (нумерованные разделы) →
H3..H6 (подразделы). Не пропускай уровни (например,
## Раздел сразу
за которым #### Пункт без ### между ними).
Основной текст
Обычный абзац. **Жирный**, *курсив*, ~~зачёркнутый~~, `моноширинный`
inline-код.
- Абзацы разделяются пустой строкой.
- Длинные строки не оборачивай вручную — markdown склеит мягкие
переносы в пробел, в docx это станет одной непрерывной строкой,
выровненной по ширине.
- Жёсткий перенос внутри абзаца — два пробела в конце строки.
Списки
- Пункт первый
- Пункт второй
- Вложенный пункт
- Ещё один
- Пункт третий
1. Первый шаг
2. Второй шаг
1. Подшаг
2. Подшаг
1. Под-подшаг
3. Третий шаг
- Маркированные — через
- (можно *, но единообразно — -). В docx
на первом уровне рендерится как «-» (дефис, ГОСТ 7.32 п. 6.5.2);
глубже — типографические буллеты ◦, ▪.
- Нумерованные — через
1., 2.. Word проставит номера сам: цифры
в исходнике могут быть любыми (1., 1., 1.), главное —
единый префикс <число>..
- Иерархия для нумерованных списков сквозная: верхний уровень —
1.,
2.; вложенный нумерованный пункт получит вид 2.1., ещё глубже —
2.1.1. и так до 9 уровней. Это сделано через один multilevel-список
в Word, поэтому в Word'е работают Tab / Shift+Tab для переключения
уровней без потери нумерации.
- Каждый верхнеуровневый нумерованный список начинает счёт заново
с
1. Чтобы продолжить нумерацию через комментарий — нельзя,
начинай новый список (это сознательный отказ для предсказуемости).
- Вложенность — отступ 2 или 4 пробела. Уровни видимо различаются
до 9.
- Не пиши маркеры вручную (
• пункт, 1) пункт) — конвертер
такие строки воспримет как обычный абзац.
- Перечень источников / литература — только нумерованным списком
(по ГОСТ 7.32, п. 8). Не используй буллеты для списков ссылок.
Изображения с подписями
-
Строка с изображением должна быть отдельным абзацем (пустые
строки сверху и снизу).
-
Alt-текст (Структура системы) становится подписью. В docx
получится (формат по ГОСТ 7.32, тире, не точка):
Рисунок 1 — Структура системы
-
Нумерация рисунков — сквозная по документу, проставляется
автоматически.
-
Если подпись не нужна, alt-текст можно оставить пустым
() — в docx подпись будет Рисунок N.
-
Изображения внутри строки текста (текст  текст)
обрабатываются как inline-иконки, без подписи и без центрирования.
Цитаты
> Цитируемый текст. Может занимать несколько строк, разделённых
> символом `>`. Поддерживает *курсив* и **жирный**.
- В docx превращается в абзац со стилем «Quote»: курсив, отступ
слева 1.25 см, тонкая серая полоса слева.
- Вложенные цитаты (
>> текст) увеличивают отступ.
- Источник цитаты, если нужен, вставляй последней строкой внутри
цитаты курсивом, например:
> *— Источник, 2024*.
Код
Inline:
Используй функцию `convert(src)` для запуска.
Блок:
```python
def hello() -> None:
print("Hello")
```
- Inline-код и блоки оформляются моноширинным шрифтом Courier New
на светло-сером фоне.
- Языковая метка после открывающих
` игнорируется
конвертером (нет подсветки синтаксиса), но не мешает.
Таблицы
Таблица: Параметры питания
| Параметр | Значение | Примечание |
| --------------- | -------- | ------------------ |
| Напряжение, В | 220 | ±10 % |
| Частота, Гц | 50 | стабилизированная |
-
Используй GFM-синтаксис с шапкой и разделителем ---.
-
Выравнивание задаётся в разделителе: :---, :---:, ---:.
-
Шапка автоматически выделяется жирным.
-
Подпись таблицы оформляется отдельным абзацем
Таблица: <Название> непосредственно перед таблицей (пустая
строка между подписью и таблицей допустима). В docx получится
(по ГОСТ 7.32, п. 6.6.3, сверху таблицы, по левому краю, обычное
начертание):
Таблица 1 — Параметры питания
-
Нумерация таблиц сквозная и проставляется автоматически.
-
Если подпись не нужна — просто не пиши строку Таблица: ….
-
Префикс Таблица: (а также Таблица ., Таблица —, Таблица -)
распознаётся без учёта регистра. Если за такой строкой не следует
таблица — она будет отрендерена как обычный абзац.
Горизонтальная линия
---
В docx — нижняя граница пустого абзаца. Используй как смысловой
разделитель между крупными блоками; не используй вместо заголовков.
Ссылки
Подробнее в [ГОСТ 7.32-2017](https://docs.cntd.ru/document/1200157208).
- Превращаются в активные гиперссылки в docx (синий цвет,
подчёркивание).
- Если внутри текста ссылки используются
** или *, форматирование
будет потеряно — оставляй ссылочный текст плоским.
Что НЕ поддерживается (и будет проигнорировано)
- HTML-блоки и inline-HTML (
<div>, <sup>, <br> и т. п.).
- Footnotes (
[^1]), task-листы (- [x]).
- Метаданные YAML/TOML в начале файла.
- Подсветка синтаксиса в кодовых блоках.
- Автоматическое оглавление (
[TOC]).
- Сноски, формулы (
$...$, $$...$$).
Если что-то из этого нужно — добавь в md так, чтобы это
конвертировалось в стандартные конструкции выше (например, формулу
вставляй картинкой).
Резюме контракта для нейросети
При генерации markdown, который будет конвертирован в .docx через
docxmd, следуй правилам:
1. Один файл .md на документ, изображения в media/.
2. Заголовки: # — структурные элементы (Введение, Заключение, Список
источников, Приложение А) без номера, по центру UPPERCASE. ## и ниже —
нумерованные разделы, автоматически получают "1", "1.1", "1.1.1".
Никогда не пиши номер в тексте заголовка вручную.
3. Абзацы — обычный текст, разделённый пустыми строками; жёсткие
переносы внутри абзаца — два пробела в конце строки.
4. Списки:
- "-" для маркированных, "1." для нумерованных;
- вложенность через отступ 2/4 пробела;
- нумерованные иерархичны: 1., 2.1., 2.1.1. — этим занимается
Word, не выписывай числа вручную;
- для перечня источников / литературы — только нумерованный
список (по ГОСТ 7.32).
5. Изображения — отдельной строкой ``.
В документе станет "Рисунок N — <подпись>" (тире по ГОСТ).
6. Таблицы — GFM с шапкой и разделителем. Подпись над таблицей:
отдельный абзац `Таблица: <Название>` непосредственно перед
таблицей. В документе станет "Таблица N — <Название>".
7. Цитаты — > строки, поддерживают вложенность.
8. Код — inline `code` и fenced ``` блоки.
9. Ссылки — [текст](url), без форматирования внутри.
10. Никаких HTML, footnotes, YAML, формул, TOC.