Стандарт формата Markdown

GFM (GitHub Flavored Markdown)  — база
  ↓
Pandoc extensions               — расширения
  ↓
Custom transclusion             — компиляция

# H1 — Название документа
## H2 — Раздел
### H3 — Подраздел
#### H4 — Пункт
##### H5 — Подпункт
###### H6 — Детализация

Параграф 1. Текст текст текст.

Параграф 2. Новый абзац.

Принудительный перенос —
добавить два пробела в конце строки.

- Элемент 1
- Элемент 2
  - Подэлемент 2.1
  - Подэлемент 2.2
- Элемент 3

1. Первый
2. Второй
   1. Подпункт 2.1
   2. Подпункт 2.2
3. Третий

- [ ] Задача не выполнена
- [x] Задача выполнена
- [ ] Частично:
  - [x] Подзадача 1
  - [ ] Подзадача 2

| Заголовок 1 | Заголовок 2 | Заголовок 3 |
|-------------|-------------|-------------|
| Ячейка 1    | Ячейка 2    | Ячейка 3    |
| Данные      | Данные      | Данные      |

| Лево | Центр | Право |
|:-----|:-----:|------:|
| L    | C     | R     |

Команда `git status` показывает статус.

```python
def hello():
    print("Hello, World!")
```

```bash
echo "Hello"
ls -la
```

[Текст ссылки](https://example.com)
[Относительная ссылка](./path/to/file.md)
[С якорем](./file.md#section-name)

[Текст ссылки][ref]

[ref]: https://example.com "Optional title"

<https://example.com>
<email@example.com>

![Alt text](./images/diagram.png)
![Alt text](./images/diagram.png "Optional title")

**Жирный** или __жирный__
*Курсив* или _курсив_
***Жирный курсив***
~~Зачёркнутый~~
`Код`

> Цитата уровень 1
>
> > Цитата уровень 2

---

---
type: standard|concept|theory|pattern|template
aspect: structure|lifecycle|process|policy|format|naming|typology|operation|guidance
title: "Название документа"
version: X.Y.Z
date: YYYY-MM-DD
status: draft|active|deprecated|archived
---

---
type: standard
aspect: format
title: "Название"
version: 1.0.0
date: 2026-02-19
status: active
author: architect
related:
  - path/to/related.md
  - path/to/another.md
depends_on:
  - path/to/dependency.md
tags:
  - markdown
  - documentation
  - hierarchy
---

Текст с сноской[^1] и ещё одной[^note].

[^1]: Текст сноски.
[^note]: Длинная сноска
    с несколькими параграфами.

Термин 1
:   Определение термина 1.

Термин 2
:   Первое определение термина 2.
:   Второе определение термина 2.

Формула $E = mc^2$ в строке.

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

::: warning
**Внимание:** Это важное предупреждение.
:::

::: example
Пример кода:
```python
print("Hello")

### Line Blocks

```markdown
| Строка 1
| Строка 2
|   Отступ
| Строка 4

MASTER.md                    ← Верхний уровень (обзор)
  ↓ ссылка
  DETAIL_1.md               ← Средний уровень (детали)
    ↓ ссылка
    SUBDETAIL_1.1.md        ← Нижний уровень (реализация)

## Детали

См. детальную документацию:
- [Детали структуры](./details/STRUCTURE_DETAILS.md)
- [Детали процесса](./details/PROCESS_DETAILS.md)

## Детали

<!-- INCLUDE: ./details/STRUCTURE_DETAILS.md -->

## Детали структуры

[→ Читать отдельно](./details/STRUCTURE_DETAILS.md)

<!-- INCLUDE: ./details/STRUCTURE_DETAILS.md -->

./file.md
./details/DETAIL.md
../sibling/FILE.md
../../parent/FILE.md

/opt/claude-workspace/architect/standards/file.md
C:\Users\...\file.md
~/workspace/file.md

## Раздел с пробелами

Ссылка: [Текст](#раздел-с-пробелами)

## ЧТО это → #что-это
## Раздел 1.2.3 → #раздел-123
## Что/Как/Где → #чтокакгде

PROJECT.md                      ← MASTER (обзор проекта)
├── details/
│   ├── ARCHITECTURE.md        ← DETAIL (архитектура)
│   │   └── impl/
│   │       ├── BACKEND.md     ← SUBDETAIL (бэкенд)
│   │       └── FRONTEND.md    ← SUBDETAIL (фронтенд)
│   ├── DATABASE.md            ← DETAIL (БД)
│   └── API.md                 ← DETAIL (API)
└── compiled/
    └── PROJECT_FULL.md        ← Скомпилированная версия

#!/usr/bin/env python3
"""
Markdown Preprocessor — компиляция иерархических документов.

Использование:
    ./md-compile.py INPUT.md OUTPUT.md
    ./md-compile.py PROJECT.md compiled/PROJECT_FULL.md
"""

import re
import sys
from pathlib import Path


def include_file(match, base_dir, depth=0, max_depth=10):
    """
    Обработка директивы <!-- INCLUDE: path -->.

    Args:
        match: regex match object
        base_dir: базовая директория
        depth: текущая глубина вложенности
        max_depth: максимальная глубина (защита от циклов)

    Returns:
        Содержимое включаемого файла или ошибка
    """
    if depth >= max_depth:
        return f"<!-- ERROR: Maximum include depth ({max_depth}) exceeded -->\n"

    include_path = match.group(1).strip()
    file_path = (base_dir / include_path).resolve()

    if not file_path.exists():
        return f"<!-- ERROR: File not found: {include_path} -->\n"

    try:
        content = file_path.read_text(encoding='utf-8')

        # Убрать frontmatter из включаемых файлов
        content = re.sub(r'^---\n.*?\n---\n', '', content, flags=re.DOTALL)

        # Рекурсивная обработка вложенных INCLUDE
        new_base = file_path.parent
        content = re.sub(
            r'<!--\s*INCLUDE:\s*(.+?)\s*-->',
            lambda m: include_file(m, new_base, depth + 1, max_depth),
            content
        )

        return content

    except Exception as e:
        return f"<!-- ERROR: {str(e)} -->\n"


def compile_document(input_path, output_path):
    """
    Компиляция документа с обработкой всех INCLUDE директив.

    Args:
        input_path: путь к исходному .md файлу
        output_path: путь к скомпилированному .md файлу
    """
    input_file = Path(input_path)
    output_file = Path(output_path)

    if not input_file.exists():
        print(f"ERROR: Input file not found: {input_path}")
        sys.exit(1)

    # Создать выходную папку
    output_file.parent.mkdir(parents=True, exist_ok=True)

    # Читать исходный файл
    content = input_file.read_text(encoding='utf-8')

    # Обработать все INCLUDE директивы
    base_dir = input_file.parent
    compiled = re.sub(
        r'<!--\s*INCLUDE:\s*(.+?)\s*-->',
        lambda m: include_file(m, base_dir),
        content
    )

    # Записать результат
    output_file.write_text(compiled, encoding='utf-8')

    print(f"✓ Compiled: {output_path}")
    print(f"  Source:  {input_path}")
    print(f"  Lines:   {len(content.splitlines())} → {len(compiled.splitlines())}")


if __name__ == '__main__':
    if len(sys.argv) != 3:
        print("Usage: md-compile.py INPUT.md OUTPUT.md")
        sys.exit(1)

    compile_document(sys.argv[1], sys.argv[2])

python3 architect/tools/md-compile.py \
  architect/standards/PROJECT.md \
  architect/standards/compiled/PROJECT_FULL.md

for file in architect/standards/*.md; do
  python3 architect/tools/md-compile.py \
    "$file" \
    "architect/standards/compiled/$(basename $file)"
done

#!/bin/bash
# .git/hooks/pre-commit

# Найти изменённые .md файлы
changed=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$')

for file in $changed; do
  # Если файл содержит INCLUDE директивы
  if grep -q '<!-- INCLUDE:' "$file"; then
    compiled="compiled/$(basename $file)"
    python3 architect/tools/md-compile.py "$file" "$compiled"
    git add "$compiled"
  fi
done

---
type: project
title: "Проект Платформа"
version: 1.0.0
date: 2026-02-19
---

# Проект Платформа

Комплексная платформа для автоматизации бизнеса.

## Архитектура

Платформа состоит из 5 подсистем.

[→ Детальная архитектура](./details/ARCHITECTURE.md)

<!-- INCLUDE: ./details/ARCHITECTURE.md -->

## База данных

Используем PostgreSQL + NocoDB.

[→ Детали БД](./details/DATABASE.md)

<!-- INCLUDE: ./details/DATABASE.md -->

---
type: detail
title: "Архитектура платформы"
parent: ../PROJECT.md
---

# Архитектура платформы

## Backend

Серверная часть на FastAPI.

[→ Детали бэкенда](./impl/BACKEND.md)

<!-- INCLUDE: ./impl/BACKEND.md -->

## Frontend

Клиентская часть на React.

[→ Детали фронтенда](./impl/FRONTEND.md)

<!-- INCLUDE: ./impl/FRONTEND.md -->

---
type: implementation
title: "Backend реализация"
parent: ../ARCHITECTURE.md
---

# Backend реализация

## Структура API

## Эндпоинты

### GET /api/v1/users
Получить список пользователей.

**Response:**
```json
{
  "users": [...]
}

### Результат компиляции

```bash
python3 md-compile.py PROJECT.md compiled/PROJECT_FULL.md

---
type: standard|concept|theory|pattern|template|project|detail|implementation
title: "Название документа"
version: X.Y.Z
date: YYYY-MM-DD
---

---
type: detail
title: "Название"
parent: ../MASTER.md  # ссылка на родителя
version: 1.0.0
date: 2026-02-19
---

[Стандарт структуры](PROJECT_STANDARD.md)

[GitHub](https://github.com)

[Перейти к разделу](#название-раздела)

# Название документа

Текст...

---
type: standard
aspect: structure
title: "Название документа"
version: 1.0.0
date: 2026-02-19
status: active
---

# Название документа

Текст...

[Файл](/opt/claude-workspace/architect/standards/file.md)

[Файл](./file.md)

## Детали

См. [детальный документ](./details/DETAIL.md).

## Детали

[→ Читать отдельно](./details/DETAIL.md)

<!-- INCLUDE: ./details/DETAIL.md -->

#!/bin/bash
# migrate-md.sh — добавить frontmatter ко всем .md без него

for file in architect/standards/**/*.md; do
  # Проверить наличие frontmatter
  if ! head -n1 "$file" | grep -q '^---$'; then
    # Извлечь название из H1
    title=$(grep -m1 '^# ' "$file" | sed 's/^# //')

    # Определить аспект из пути
    aspect=$(dirname "$file" | grep -oP '\d-\K\w+')

    # Создать временный файл с frontmatter
    cat > "$file.tmp" <<EOF
---
type: standard
aspect: $aspect
title: "$title"
version: 1.0.0
date: $(date +%Y-%m-%d)
status: active
---

EOF

    # Добавить содержимое
    cat "$file" >> "$file.tmp"

    # Заменить файл
    mv "$file.tmp" "$file"

    echo "✓ Added frontmatter: $file"
  fi
done

# Найти все .md без frontmatter
grep -L '^---$' architect/standards/**/*.md

# Найти абсолютные пути
grep -r '\](/\|file://\|C:\\' architect/standards/**/*.md

# Использовать markdown-link-check
npm install -g markdown-link-check
markdown-link-check architect/standards/**/*.md

pandoc -f markdown -t html5 \
  --standalone \
  --css=style.css \
  --mathjax \
  input.md -o output.html

pandoc -f markdown -t pdf \
  --pdf-engine=xelatex \
  --variable mainfont="DejaVu Sans" \
  input.md -o output.pdf