feat(converter): implement deterministic JSON to Markdown article converter (spec 005)

2026-08-21 10:30:14 -03:00
parent 64dfd842de
commit 926a6b8cfc
58 changed files with 20138 additions and 2301 deletions
@@ -0,0 +1,38 @@
+# Markdown Schema Contract: Output Article Markdown
+
+**Feature**: `005-convert-json-markdown` | **Date**: 2026-08-21
+
+## 1. Output Document Specification
+
+The generated Markdown document MUST strictly adhere to the following template structure:
+
+```markdown
+# {Resolved Title}
+
+{Resolved Subtitle/Description - OMITTED IF ABSENT OR EQUAL TO TITLE}
+
+**Autor:** {Resolved Authors joined by ", " - OMITTED IF ABSENT}
+**Publicado em:** {Resolved Publication Date - OMITTED IF ABSENT}
+**Site:** {Resolved Site Name - OMITTED IF ABSENT}
+**Categoria:** {Resolved Categories joined by ", " - OMITTED IF ABSENT}
+**Tags:** {Resolved Tags joined by ", " - OMITTED IF ABSENT}
+**Palavras-chave:** {Resolved Keywords joined by ", " - OMITTED IF ABSENT}
+**Idioma:** {Resolved Language Code - OMITTED IF ABSENT}
+**Fonte original:** [{Resolved Original URL}]({Resolved Original URL})
+
+![Imagem principal]({Resolved Top Image URL - OMITTED IF ABSENT})
+
+---
+
+{Converted Markdown Body Content}
+```
+
+## 2. Formatting & Syntax Constraints
+
+1. **Character Encoding**: UTF-8 without BOM.
+2. **Line Delimiters**: UNIX-style `LF` (`\n`).
+3. **Trailing Whitespace**: Stripped from every line.
+4. **Blank Lines**: Maximum of 2 consecutive newline characters (`\n\n`), preventing excessive vertical spacing.
+5. **EOF Delimiter**: Ends with exactly one trailing newline character (`\n`).
+6. **No Placeholders**: Never print `null`, `None`, `N/A`, `unknown`, `[no-author]`, or empty metadata labels (e.g. `**Autor:** `).
+7. **No Internal Leakage**: Never output `selected_extractor` name, scoring metrics, or JSON internals in the final document.