tf_provider/HISTORY/2026-08-10_man_format_fix.md

MAN Format Fix — 2026-08-10

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

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

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

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

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

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

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

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

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

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

<!-- Рендерится как: -->
<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 (больше не нужен)