md2pdf/docs/specs/2026-07-27-md2doc-design.md

md2doc — design spec

Data: 2026-07-27 Autor: Sebastian Petrescu Stare: draft (pending empirical review)

---

1. Obiectiv

Construieste md2doc.py — un utilitar single-file Python care converteste Markdown la .docx (Microsoft Word OOXML), simetric cu md2pdf.py existent. In acelasi plan: bug-fixes pentru md2pdf.py identificate in timpul brainstorming-ului.

2. Context

md2pdf.py exista, functioneaza (verified: rularea pe pluxee-todo.md produce PDF byte-identic cu cel committed), dar are 2 bug-uri:

• B1. convert_md_to_pdf() accepta parametru footer, dar argparse nu expune flag-ul --footer. Functionalitate moarta in CLI.
• B2. --forms ruleaza fara eroare, dar nu produce campuri AcroForm. Verificare: PDF-ul rezultat nu contine /AcroForm si nici anotari /Widget. weasyprint nu genereaza campuri de formular din <input> HTML in mod automat.

Pentru md2doc: niciun work anterior in AW pe conversie md→docx. Research extern (web-search-prime) arata 3 abordari posibile: Pandoc (CLI/subprocess), pypandoc (wrapper), sau python-docx cu parsare manuala. Am ales a treia pentru a pastra controlul fin asupra stilurilor si consistenta cu md2pdf.py.

3. Arhitectura

3.1 Layout repository

tools/
├── md2pdf.py     (existing — bug fixes only, scope-limited)
├── md2doc.py     (new — sibling, mirrors md2pdf structure)
└── docs/specs/2026-07-27-md2doc-design.md

md2doc.py este single-file, simetric cu md2pdf.py. Nu se face refactor spre package comun — YAGNI pentru 2 fisiere.

3.2 Structura md2doc.py

Pattern duplicat din md2pdf.py:

#!/usr/bin/env python3
import argparse, sys
from pathlib import Path
import markdown
from bs4 import BeautifulSoup
from docx import Document
from docx.shared import Pt, RGBColor, Cm

STYLES = {
    "elegant": {...},  # default
    "report":  {...},
    "default": {...},
    "dark":    {...},
    "mono":    {...},
}

COMMON = {...}  # reguli comune, ca si COMMON_CSS in md2pdf

def convert_md_to_doc(md_file, output_file, style="elegant", footer=""):
    ...

def main():
    parser = argparse.ArgumentParser(...)
    ...

3.3 Pipeline conversie

md text
  ↓ _bulletize()             (reutilizat din md2pdf — scos ca util comun)
  ↓ markdown.markdown()       (extensii: tables, fenced_code, toc, attr_list, nl2br)
  ↓ BeautifulSoup HTML
  ↓ walk DOM, emit docx elements
.docx file

_bulletize() e duplicated logic between md2pdf and md2doc. Pentru scope-ul curent (2 fisiere), se copiaza. Daca pe viitor se adauga un al 3-lea converter, se refactor la un md_utils.py comun.

4. Mapare stiluri (md → docx)

Fiecare stil din STYLES defineste echivalentele Word ale CSS-ului md2pdf. Mapping-ul e manual, element cu element.

Element MD	md2pdf (CSS)	md2doc (Word)
h1	font-size + border-bottom	Heading 1 style + paragraph bottom border
h2/h3/h4	font-size + color	Heading 2/3/4 style
p	line-height + color	paragraph format
strong	font-weight 700	run.bold = True
em	italic	run.italic = True
code (inline)	monospace + bg	run.font.name = mono + run highlight
pre	block + border-left	paragraph + indent + shading
blockquote	border-left + bg	paragraph left indent + italic + shading
table	borders + header bg	docx Table + cell shading + borders
ul/ol	list markers	List Bullet / List Number paragraph styles
a	color + underline	run.color + run.underline
hr	border-top	paragraph bottom border

4.1 Ipoteze de verificat (HARD CLAIMS — astea trebuie validate empiric inainte de implementare)

Urmatoarele afirmatii despre python-docx sunt ipoteze, nu fapte, pana cand reviewer-ul empiric le rupe sau le confirma cu comenzi reale:

• H1. python-docx poate adauga bottom border pe un paragraph Heading 1 (necesita manipulare XML — Issue python-docx #105 sugereaza ca nu exista API direct).
• H2. python-docx poate aplica shading pe un paragraph (pentru code/blockquote) — documentatia oficiala nu listeaza API;StackTrace-ul sugereaza XML manipulation cu OxmlElement('w:shd').
• H3. python-docx poate crea liste nested (Level 2, Level 3) care se randeaza corect in Word SI Google Docs. Issue #122 si thread-urile Latenate/Reddit sugereaza probleme cunoscute aici.
• H4. Cell shading (w:shd pe w:tcPr) functioneaza pentru background de header row intr-un tabel.
• H5. style = document.styles['List Bullet'] exista intr-un Document nou creat de python-docx (sau trebuie adaugat manual).

Pana nu se valideaza H1-H5 cu comenzi reale (run python-docx, deschide output in Word/Pages, verifica vizual), mapping-ul din tabel este plan, nu fapt.

5. CLI interface

Identica cu md2pdf.py:

md2doc.py input.md                      # → input.docx
md2doc.py input.md -o output.docx
md2doc.py docs/                         # converteste toate .md din docs/
md2doc.py input.md --style mono
md2doc.py input.md -q                   # quiet

6. Bug-fixes md2pdf.py (scope-limited)

6.1 B1: expunere --footer

Adauga argument argparse:

parser.add_argument('--footer', help='Custom footer text (right-aligned)')

Si paseaza-l in apelul convert_md_to_pdf(md_file, pdf_file, args.style, forms=args.forms, footer=args.footer).

6.2 B2: --forms nu produce AcroForm

Fapt stabilit (verified): weasyprint 68.1 nu genereaza campuri de formular din <input type="text"> sau <textarea> din HTML-ul stringify-uit. Markul HTML e prezent (verified: markdown.markdown() produce <input ...> corect), dar weasyprint il randeaza ca text static.

Ipoteza (de verificat): weasyprint necesita ca HTML-ul sa fie incarcat ca string cu base_url setat, sau tag-urile <form> sa fie wrappate explicit, sau exista un flag documentat presentational_hints=True.

Alternativ: daca weasyprint 68.1 nu suporta forms deloc, atunci flag-ul --forms trebuie eliminat din md2pdf (YAGNI) sau documentat ca no-op cu eroare loud.

Inainte de implementare, reviewer-ul empiric verifica care varianta e adevarata.

7. Dependencies

md2doc.py:

• python-docx (NOU — pip install python-docx)
• markdown (deja instalat, v3.10.2)
• beautifulsoup4 (trebuie verificat daca e instalat)
• lxml (parser pentru BeautifulSoup, mai rapid decat html.parser)

md2pdf.py:

• existente, niciun nou dep.

8. Error handling

Fail-loud, niciodata silent. Pe orice eroare de parsare/conversie:

• print la stderr cu context (file, line if available)
• sys.exit(1) cu mesaj
• nu se scrie fisier de output partial

9. Testing

• md2doc: PT urmeaza pattern-ul md2pdf — nu exista test suite inca. Pentru MVP: convertim pluxee-todo.md si un edge-case file, verificam ca output .docx se deschide in Word/Pages fara erori si ca structura (headings, lists, tables, code blocks) e corecta vizual.
• md2pdf bug-fixes: dupa B1, rulam md2pdf.py input.md --footer "Test" si verificam ca footer-ul apare in PDF. Pentru B2, depinde de verdictul empiric.

10. Out of scope

• Refactor md2pdf + md2doc la un package comun (YAGNI pentru 2 fisiere)
• Stiluri noi peste cele 5 existente
• Suport pentru images embedded in markdown (de tratat separat)
• Suport pentru syntax highlighting in code blocks (Pygments integration)
• .doc (format vechi binar) — doar .docx
• Integrare cu reference.docx templates (pandoc-style)