docs: MAN format fix history + instructions (??? admonition, not details/div)

2026-08-10 17:16:54 +04:00
parent b97edf9f57
commit dc5bac376c
2 changed files with 112 additions and 1 deletions
@@ -0,0 +1,66 @@
+# 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 (больше не нужен) |
@@ -31,7 +31,7 @@ S3 (terraform-registry) ── хостинг через registry.kube5s.ru  <!-

 | Файл | Содержание |
 |---|---|
-| `Name.md` | Главная: MAN (переведён в Markdown), навигация |
+| `Name.md` | Главная: краткое описание + MAN в `??? note` (mkdocs-native admonition) |
 | `Name_example.md` | HCL-пример с полным манифестом |
 | `Name_params_create.md` | Таблицы Create-параметров + вложенные sub_params |
 | `Name_params_modify.md` | Таблицы Modify-параметров |
@@ -41,6 +41,51 @@ S3 (terraform-registry) ── хостинг через registry.kube5s.ru  <!-
 | `Name_subresource.md` | Для каждого subresource: параметры |
 | `Name_subresource_example.md` | HCL-пример subresource |

+## Формат MAN (service_man) — как рендерится
+
+`service_man` из YAML содержит **смесь Markdown и HTML**: заголовки `#`/`##`, списки `-`, bold `**`, горизонтальные линии `---`, а также `<br/>` и HTML-entities.
+
+### Конвертация: `htmlToMarkdown()`
+
+```go
+// 1. <br/> → \n
+// 2. <h1>/<h2>/<h3> → # / ## / ###
+// 3. <strong>/<b> → **...**
+// 4. <em>/<i> → *...*
+// 5. <code> → `...`
+// 6. <a href> → [...](...)
+// 7. <ul><li> → - ...
+// 8. Strip remaining HTML tags
+// 9. Unescape HTML entities (&quot; → ")
+// 10. Collapse 3+ blank lines → 2
+```
+
+### Рендеринг: `??? note` admonition (НЕ `<details>`!)
+
+**Важно:** `<details>` и `<div markdown="1">` НЕ работают в mkdocs — Markdown внутри них не рендерится.
+
+Вместо этого используется **нативный mkdocs admonition** `??? note`:
+
+```markdown
+??? note "Справка (MAN)"
+
+    # Инструкция по развертыванию
+    
+    ---
+    ## 1. Общая информация
+    Текст параграфа.
+    
+    - **bold** — описание
+    - `code` — пример
+```
+
+**Критические требования:**
+1. Пустая строка после `??? note "..."` — обязательно
+2. Все строки контента с отступом ровно 4 пробела — включая пустые
+3. `pymdownx.details` в `markdown_extensions` (уже есть)
+
+Результат: `<details class="note"><summary>Справка (MAN)</summary><h1>...</h1><hr/><h2>...</h2>...</details>`
+
 ## Принципы дизайна (CSS)

 - `max-width: 1800px` — лёгкое ограничение (на 2560px поля ~380px)