# Template-Driven Publishing Usa questo riferimento quando devi produrre deliverable rigenerabili da Markdown verso DOCX, PDF o HTML mantenendo coerenza visiva tra modifiche successive. Template e profili sono opzionali: usali quando serve governare stile, brand o layout; per conversioni semplici e' accettabile una pipeline Pandoc plain. ## Principio Separa sempre: - sorgente editoriale: Markdown semantico; - asset master: SVG, sorgenti grafici, immagini originali; - asset derivati: PNG/JPG generati per target che non gestiscono bene il master; - template di stile opzionali: DOCX reference, LaTeX/HTML template, metadata Pandoc; - artefatti finali: DOCX, PDF, HTML rigenerabili. Non modificare manualmente gli artefatti finali quando possono essere rigenerati dalla pipeline. ## Markdown Sorgente Il Markdown deve descrivere struttura e contenuto: - titoli e sottotitoli; - paragrafi; - liste ordinate e non ordinate; - citazioni o note; - tabelle semplici; - riferimenti immagini con dimensioni dichiarate. Evita nel Markdown: - font, margini e spaziature manuali; - workaround specifici di un solo target; - duplicazioni del contenuto per DOCX e PDF; - path assoluti quando basta un path relativo stabile. ## Profili Di Pubblicazione Un profilo raccoglie convenzioni riusabili per un'identita' visiva o una classe di documenti. Struttura consigliata: ```text skills/mcp-office-expert/assets/templates// profile.json reference.docx reference-seed.md pdf-template.tex html-template.html ``` Questi template bundled sono visibili quando la skill viene installata o riusata fuori dal repository corrente. Template specifici di un singolo progetto possono stare nel progetto, ma non devono essere l'unica copia di un profilo riusabile. Non tutti i file sono obbligatori. Usa solo quelli necessari al target. Esempio di profilo: ```json { "name": "sophia", "docx": { "reference_doc_path": "reference.docx", "image_policy": "png" }, "pdf": { "template_path": "pdf-template.tex", "pdf_engine": "xelatex", "image_policy": "pdf-vector" } } ``` Esempio concettuale di policy asset: ```yaml assets: master: svg docx_derivative: png pdf_derivative: pdf-vector ``` ## DOCX Per DOCX con stile coerente usa `document_convert.convert` con `reference_doc_path`. Per il profilo Sophia bundled usa: ```text skills/mcp-office-expert/assets/templates/sophia/reference.docx ``` Per analisi tecniche in formato Tesisquare AT usa: ```text skills/mcp-office-expert/assets/templates/tesisquare/reference.docx ``` Il reference DOCX governa: - stili `Title`, `Heading 1`, `Heading 2`, `Normal`, liste e citazioni; - font, colori, interlinea, spaziature; - margini, intestazioni e piedi pagina se necessari. Per immagini vettoriali, preferisci usare PNG derivati da SVG master quando il DOCX deve essere aperto in Word o scambiato con utenti non tecnici. Conserva sempre gli SVG come sorgenti. ### Profili DOCX Con Frontespizio Pandoc usa `reference_doc_path` come documento di stile: importa stili, margini, font, intestazioni/piedi e proprietà del documento, ma non inserisce nel file finale i contenuti presenti nel reference. Frontespizi, loghi, immagini di introduzione, tabelle di revisione e disclaimer devono essere scritti nel Markdown sorgente o generati con uno step Word successivo. Quando usi un profilo bundled che contiene `reference-seed.md`, trattalo come esempio canonico della struttura da replicare. Per il profilo Tesisquare, il seed mostra l'immagine iniziale e il frontespizio; se il documento finale li richiede: 1. copia o referenzia gli asset necessari dal profilo, ad esempio `assets/templates/tesisquare/assets/cover-logo.jpg`; 2. inserisci nel Markdown l'immagine con dimensione esplicita, ad esempio `![](assets/cover-logo.jpg){width=7.4in}`; 3. passa a `document_convert.convert` un `resource_paths` che includa la cartella del Markdown o degli asset; 4. verifica il DOCX generato con `word_document.list_paragraphs` e, quando serve, ispeziona il pacchetto DOCX o una copia del file per confermare che esista una voce `word/media/*`. ### Tabelle Markdown In DOCX Le tabelle Markdown sono comode per dati semplici, ma nei profili Word con header/footer, stili tabella complessi o larghezze pagina vincolate possono renderizzare male: celle vuote, colonne stirate, testo sovrapposto al footer, righe spezzate o contenuti apparentemente usciti dalla tabella. Per documenti cliente in DOCX: - evita tabelle Markdown per frontespizi, revisioni, firme, approvazioni e mini riepiloghi economici; - preferisci elenchi o paragrafi `Etichetta: valore` quando la tabella ha pochi campi; - se una tabella è davvero necessaria, mantienila stretta, senza celle vuote e con poche colonne; poi verifica il risultato in Word; - non assumere che l'assenza di errori Pandoc equivalga a layout corretto. Checklist minima post-conversione DOCX: 1. esegui `word_document.list_paragraphs` e controlla titolo, frontespizio, sezioni, liste e riepiloghi numerici; 2. cerca segnali di degrado: intestazioni duplicate, paragrafi collassati, campi `Funzione/Nome/Data` sulla stessa riga, valori tabellari separati dal loro titolo; 3. se hai inserito immagini, verifica che il file DOCX cresca di dimensione e, se possibile, controlla le entry `word/media/*` su una copia non aperta da Word o da anteprime; 4. se il file è bloccato da Word/preview, non forzare la scrittura: chiudi il viewer o genera una nuova versione con suffisso esplicito. ## PDF Per PDF generati da Markdown, preferisci asset vettoriali. Prova SVG diretto solo quando il renderer lo supporta nel runtime effettivo. Con Pandoc, verifica prima `document_convert.status` e usa un engine disponibile, di norma `xelatex` per documenti aziendali. Se un PDF minimale funziona ma un PDF con SVG fallisce, non concludere che l'engine PDF manca: il problema puo' essere la conversione SVG nel runtime Pandoc/LaTeX. In quel caso usa la skill `svg` per esportare gli SVG master in PDF vettoriali e fai puntare il Markdown PDF a quei derivati. Usa PNG solo come fallback non vettoriale. Il PDF deve ricevere la formattazione da: - metadata Pandoc; - template LaTeX/HTML quando necessario; - asset SVG master o PDF vettoriali derivati da SVG master. Il template PDF deve dichiarare la lingua. Se il documento contiene molti termini tecnici o inglesi, disabilita la sillabazione automatica o definisci eccezioni esplicite: spezzature come `repos-itory` o `oper-ativo` sono da trattare come difetti di layout, non come resa accettabile. Per il profilo Sophia bundled usa: ```text skills/mcp-office-expert/assets/templates/sophia/pdf-template.tex ``` Per il profilo Tesisquare AT usa: ```text skills/mcp-office-expert/assets/templates/tesisquare/pdf-template.tex ``` ## HTML Per HTML usa `template_path` quando serve un layout controllato. Mantieni CSS e asset in cartelle versionate vicino al template o nel profilo. ## Asset Regole minime: - SVG e sorgenti originali sono master; - PNG/JPG esportati sono derivati rigenerabili; - i derivati devono essere generati da script o workflow dichiarato; - non modificare a mano i derivati; - dichiara sempre dimensioni immagine nel Markdown quando impattano il layout. Per lavori SVG tecnici usa la skill `svg`: validazione XML/SVG, palette, helper geometrici, export PNG/PDF e QA visiva. ## Pipeline Raccomandata 1. Valida che Pandoc e gli engine richiesti siano disponibili. 2. Valida che eventuali template e asset master esistano. 3. Rigenera asset derivati necessari al target. 4. Per DOCX, crea una copia temporanea del Markdown con asset derivati se serve. 5. Genera DOCX con `reference_doc_path`. 6. Genera PDF dal Markdown sorgente usando SVG quando supportato; altrimenti usa PDF vettoriali derivati dagli SVG. 7. Verifica output: file creati, media embedded, testo leggibile, immagini non mancanti. 8. Se il documento deve restare ricercabile, indicizzalo con `mcp-docs-navigator`. Per uso diretto fuori MCP, usa lo script bundled: ```bash node skills/mcp-office-expert/tools/publish-markdown-document.js --list-profiles --pretty node skills/mcp-office-expert/tools/publish-markdown-document.js --source --profile sophia --pretty node skills/mcp-office-expert/tools/publish-markdown-document.js --source --profile tesisquare --pretty node skills/mcp-office-expert/tools/publish-markdown-document.js --source --no-template --targets docx --pretty ``` Lo script applica il profilo quando indicato, oppure usa Pandoc plain con `--no-template`. Genera derivati asset, produce DOCX/PDF e scrive un report JSON con verifiche. La QA visiva PDF renderizza la prima pagina quando nel PATH e' disponibile `pdftoppm`, `mutool` o `magick`; in caso contrario il report dichiara un warning non bloccante. Per ambienti esterni senza PATH configurato, usa `--pandoc `, `--inkscape ` e `--pdf-engine `. Per setup esterno usa l'installer repository: `pandoc` e `inkscape` coprono la conversione base, `xelatex` e' la dipendenza opzionale raccomandata per PDF aziendali completi e formule, `latex_packages` preinstalla i pacchetti `.sty` usati dai template Pandoc/LaTeX per evitare popup MiKTeX, `poppler` abilita QA visuale tramite `pdftoppm`. ## Quando Promuovere A MCP Mantieni il workflow come skill + script finche' naming, template e controlli sono ancora in evoluzione. Valuta un tool MCP dedicato solo quando: - il workflow si ripete su piu' documenti o progetti; - i parametri sono stabili; - serve output strutturato con check standard; - gli errori ricorrenti giustificano un contratto tool piu' rigido.