CONTENTGUIDE

This file documents the markdown conventions the diploma DOCX renderer expects. For the full pipeline, the placeholder map, and the trace chain, see AGENT_GUIDE.md at repo root.

Where things live

• content/3.diplom-artem/ — Артём
• content/4.diplom-danya/ — Даня

Each diploma follows the same skeleton:

0.index.md                  # frontmatter with diploma metadata; site index
1.referat.md                # Реферат
2.abbreviations.md          # Перечень сокращений
3.introduction.md           # Введение
4.chapter-1/
  README.md                 # H1 = "Глава 1. ..." + intro prose
  context-and-problem.md    # subsections (## 1.1, ## 1.2 ...)
  figures/                  # PNGs referenced from chapter md
5.chapter-2/...
6.chapter-3/...
7.chapter-4/...
8.conclusion.md             # Заключение
9.sources.md                # Список использованных источников
appendices/
  README.md

0.index.md frontmatter

This is the SINGLE source of truth for everything on the title page:

diploma:
  filename: diplom-artem.docx
  title: Диплом Артема
  topic: Разработка серверной части ...
  studentName: Переятенцев Артем Олегович
  studentGroup: ""
  supervisor: Галушин С.Я.
  consultant: Пирогов А.А.
  headOfDept: Галушин С.Я.
  faculty: корабельной энергетики и автоматики
  department: судовой автоматики и измерений
  direction: 10.03.01 Информационная безопасность
  profile: 10.03.01.04 Безопасность автоматизированных систем
  qualification: БАКАЛАВРА
  year: "2026"

Missing required fields cause an explicit error. Person names accept either the short form (Фамилия И.О.) or the full form (Иванов Иван Иванович); the renderer reduces the latter to initials.

Headings inside chapters

A chapter is README.md + sibling files.

README.md:

---
title: Глава 1. Анализ предметной области и требований к платформе
---

# Глава 1. Анализ предметной области и требований к платформе

В главе рассматриваются ... (intro prose only, no bullet list of links).

- [Контекст, проблема и требования](./context-and-problem)   ← drop / move to site nav

The bullet list of [text](./link) lines is for the website navigation. The renderer strips it from the DOCX automatically.

Sibling file (e.g. context-and-problem.md):

---
title: Контекст, проблема и требования
---

# Контекст, проблема и требования     ← will be DROPPED at concat time

## 1.1 Роль ...

## 1.2 Ограничения ...

The first H1 in the inner file is dropped because it duplicates the chapter heading. Subsections live at ## level so they appear in the TOC (toc-depth=3).

Figures

Target style (drawio / excalidraw / hand-exported PNG)

Графически связь компонентов показана на схеме ниже:

![Логическая связь пользователя и проверяемого ресурса](./figures/auth.png){#fig:auth width=80%}

Из схемы видно, что доступ ... (refer to it via [@fig:auth]).

• PNG file: <chapter>/figures/<label>.png.
• {#fig:auth ...} is the pandoc-crossref label. Use fig: prefix for figures.
• Caption text comes from the markdown alt text — pandoc-crossref prepends "Рисунок N — ".
• In-text reference: [@fig:auth] → "рисунок N".
• width=80% keeps it inside the print margins; tune per image.

Mermaid (transitional)

The site still renders mermaid. To get the same diagram into DOCX:

```mermaid {#fig:auth caption="Логическая связь пользователя"}
flowchart LR
    User --> Membership --> Group
    ...
```

Then run once locally:

pnpm diploma:figures

This invokes @mermaid-js/mermaid-cli (downloads Chromium on first run) and writes ./figures/auth.png. The PNG is committed alongside the markdown. The cache (.figures-cache.json) tracks block content hashes so unchanged diagrams are skipped.

When the DOCX is generated:

• If ./figures/auth.png exists → mermaid block is rewritten in-stream as ![caption](./figures/auth.png){#fig:auth}.
• If the PNG is missing → mermaid block is dropped silently; any manual «Рисунок 1.1 — ...» paragraph that follows still ships as plain text.

Long-term plan: replace mermaid blocks with hand-drawn drawio/excalidraw exports. Once a chapter has only PNGs in figures/, you can delete the mermaid block entirely.

Tables

Standard markdown pipe tables work as-is. For an auto-numbered caption, use pandoc-crossref's table caption syntax — the line BEFORE the table:

: Метрики производительности API {#tbl:perf}

| VUs | P50 | P95 |
| --- | --- | --- |
| 10  | 45  | 82  |

Reference in text: [@tbl:perf] → «таблица N».

Manual «Таблица 4.2 — ...» captions stay as ordinary paragraphs (no link, no auto-number).

Code listings

Inline fenced code blocks stay as monospaced runs. For a numbered listing:

```{.json #lst:onboarding caption="Структура ответа API при Onboarding"}
{
  "profile": { "username": "ivanov_teacher" }
}
```

The caption becomes «Листинг N — Структура ответа API при Onboarding». Reference: [@lst:onboarding].

Sources (9.sources.md)

• Manual numbered list (1. ..., 2. ...).
• Format: Фамилия И. О. Заглавие. Издательство, год. URL: ... (дата обращения: ДД.ММ.ГГГГ). — ГОСТ Р 7.0.100-2018.
• In text, references stay as plain [1], [12, с. 45]. No auto-resolution.

Appendices

Each appendix is a separate markdown file in appendices/ with H1 «Приложение А» / «Приложение Б». Appendices are page-break-separated and listed in the TOC.

Cross-reference cheat sheet

Things the renderer does NOT do

• Footnotes ([^1]) — not styled per GOST; avoid in DOCX-bound content.
• HTML embedded in markdown — --from=markdown+raw_html-implicit_figures parses raw HTML, but layout is not guaranteed.
• Custom mermaid themes — the dev script renders with the default theme; if you need a different look, export from drawio/excalidraw instead.
• Auto-resolving [1] source refs as links to 9.sources.md. They stay as text.