# MAN Format Fix — 2026-08-10

**Проблема:** `service_man` из YAML содержит Markdown (`#`, `##`, `---`, `**`) + HTML (`<br/>`, `&quot;`), но рендерился как сырой текст. Теги `##`, `**`, `---` выводились буквально, не форматируя текст.

**Корень проблемы:** `md_in_html` расширение mkdocs не обрабатывает Markdown внутри `<div markdown="1">` и `<details>` — всё содержимое выводится как plain text.

**Решение:** использовать **нативный mkdocs admonition** `??? note` вместо HTML-тегов.

### Было (сломано)

```go
b.WriteString("<details class=\"man-content\">\n<summary>Справка (MAN)</summary>\n\n")
b.WriteString(htmlToMarkdown(man))
b.WriteString("\n\n</details>\n")
```

```html
<!-- Рендерилось как: -->
# Инструкция --- ## 1. Общая информация **текст**
<!-- Все теги видны буквально -->
```

### Стало (работает)

```go
b.WriteString("??? note \"Справка (MAN)\"\n\n")
md := htmlToMarkdown(man)
for _, line := range strings.Split(md, "\n") {
    b.WriteString("    " + line + "\n")
}
b.WriteString("\n")
```

```markdown
??? note "Справка (MAN)"

    # Инструкция по развертыванию
    
    ---
    ## 1. Общая информация
    **текст**
```

```html
<!-- Рендерится как: -->
<details class="note">
  <summary>Справка (MAN)</summary>
  <h1>Инструкция по развертыванию</h1>
  <hr />
  <h2>1. Общая информация</h2>
  <p><strong>текст</strong></p>
</details>
```

### Ключевые требования `???` admonition

1. **Пустая строка** после `??? note "Заголовок"` — ОБЯЗАТЕЛЬНА
2. **Все строки контента** с отступом ровно 4 пробела — включая пустые строки
3. `pymdownx.details` должен быть в `markdown_extensions` (уже есть)

### Затронутые файлы

| Файл | Изменение |
|------|-----------|
| `writers/writers.go:buildManualPage()` | `??? note` вместо `<details>` |
| `extra.css` | Убран `.man-content` CSS (больше не нужен) |