Export PDF/Word

Perché Esportare?

Non tutti gli stakeholder usano Git o leggono markdown. L'export in PDF e Word permette di condividere specifiche professionali con project manager, clienti e altri stakeholder che preferiscono formati tradizionali. I documenti esportati mantengono la formattazione completa, inclusi diagrammi, tabelle, blocchi di codice e immagini, garantendo una presentazione curata e leggibile in ogni contesto.

Why Export?

Not all stakeholders use Git or read markdown. PDF and Word export allows sharing professional specs with project managers, clients, and other stakeholders who prefer traditional formats. Exported documents retain full formatting, including diagrams, tables, code blocks, and images, ensuring a polished and readable presentation in any context.

Export PDF con Template Eisvogel

MdExplorer usa Pandoc con il template Eisvogel per generare PDF professionali. Il template è incluso automaticamente nella cartella .md/templates/pdf/eisvogel.tex di ogni progetto.

Caratteristiche del PDF generato

• Header e footer personalizzati — Con titolo del documento, autore e numero di pagina.
• Table of contents automatico — Generato dal front matter YAML con profondità configurabile.
• Syntax highlighting — I blocchi di codice vengono renderizzati con colorazione sintassi professionale.
• Supporto per immagini e diagrammi PlantUML — Tutti i diagrammi inline vengono renderizzati e inclusi nel PDF finale.

PDF Export with Eisvogel Template

MdExplorer uses Pandoc with the Eisvogel template to generate professional PDFs. The template is automatically included in the .md/templates/pdf/eisvogel.tex folder of each project.

Generated PDF features

• Custom header and footer — With document title, author, and page number.
• Automatic table of contents — Generated from YAML front matter with configurable depth.
• Syntax highlighting — Code blocks are rendered with professional syntax coloring.
• Support for images and PlantUML diagrams — All inline diagrams are rendered and included in the final PDF.

Export Word con reference.docx

Per esportare in formato Word, MdExplorer usa un file reference.docx come template di stile. Il template si trova in .md/templates/word/reference.docx e definisce l'aspetto di tutti i documenti Word generati.

Personalizzazione degli stili

Puoi personalizzare il template per adattarlo al brand della tua azienda o al formato richiesto dai tuoi stakeholder:

1. Apri il file reference.docx in Microsoft Word.
2. Modifica gli stili del documento: Heading 1, Heading 2, Normal, Code, e tutti gli altri stili che desideri personalizzare.
3. Salva il file. Tutti i futuri export utilizzeranno automaticamente i tuoi stili personalizzati.

MdExplorer include anche template aggiuntivi come minute.docx, pensato per i verbali di riunione, e una cartella pages/ per template specifici per tipo di documento.

Word Export with reference.docx

For Word export, MdExplorer uses a reference.docx file as a style template. The template is located in .md/templates/word/reference.docx and defines the appearance of all generated Word documents.

Customizing styles

You can customize the template to match your company branding or the format required by your stakeholders:

1. Open the reference.docx file in Microsoft Word.
2. Edit the document styles: Heading 1, Heading 2, Normal, Code, and any other styles you want to customize.
3. Save the file. All future exports will automatically use your custom styles.

MdExplorer also includes additional templates such as minute.docx, designed for meeting minutes, and a pages/ folder for document-type-specific templates.

YAML Front Matter per Metadati

Ogni file markdown può includere un blocco YAML front matter in cima al documento per definire i metadati. Questi metadati vengono usati durante l'export per popolare automaticamente campi come titolo, autore e data nel documento generato.

---
title: "Analisi Funzionale - Modulo Artigiano"
author: "Team Errantia"
date: "2024-12-31"
version: "1.0"
lang: "it"
toc: true
toc-depth: 3
---

Campi supportati

• title — Titolo del documento, visualizzato nel frontespizio e nell'header.
• author — Autore o team responsabile del documento.
• date — Data del documento, tipicamente nel formato YYYY-MM-DD.
• version — Versione del documento per tracciare le revisioni.
• lang — Lingua del documento (es. "it", "en"), usata per la sillabazione e le convenzioni tipografiche.
• toc — Se impostato a true, genera un table of contents automatico.
• toc-depth — Profondità del table of contents (es. 2 per mostrare solo h1 e h2, 3 per includere h3).
• subtitle — Sottotitolo del documento, visualizzato sotto il titolo nel frontespizio.
• abstract — Breve riassunto del documento, incluso prima del contenuto principale.
• keywords — Parole chiave per la categorizzazione del documento.

YAML Front Matter for Metadata

Each markdown file can include a YAML front matter block at the top to define document metadata. This metadata is used during export to automatically populate fields such as title, author, and date in the generated document.

---
title: "Functional Analysis - Artisan Module"
author: "Team Errantia"
date: "2024-12-31"
version: "1.0"
lang: "en"
toc: true
toc-depth: 3
---

Supported fields

• title — Document title, displayed on the title page and in the header.
• author — Author or team responsible for the document.
• date — Document date, typically in YYYY-MM-DD format.
• version — Document version for tracking revisions.
• lang — Document language (e.g. "it", "en"), used for hyphenation and typographic conventions.
• toc — When set to true, generates an automatic table of contents.
• toc-depth — Table of contents depth (e.g. 2 to show only h1 and h2, 3 to include h3).
• subtitle — Document subtitle, displayed below the title on the title page.
• abstract — Brief document summary, included before the main content.
• keywords — Keywords for document categorization.

Personalizzazione Template

I template si trovano nella cartella .md/templates/ del progetto. Questa cartella viene creata automaticamente quando apri un progetto con MdExplorer e contiene tutti i file necessari per l'export.

.md/templates/
├── pdf/
│   └── eisvogel.tex     (template LaTeX per PDF)
└── word/
    ├── reference.docx   (template stili Word)
    ├── minute.docx      (template verbali)
    └── pages/           (template aggiuntivi)

Variabili Eisvogel per PDF

Per personalizzare l'aspetto del PDF, puoi aggiungere variabili specifiche di Eisvogel nel blocco YAML front matter del tuo file markdown:

• titlepage — true o false, abilita o disabilita il frontespizio.
• titlepage-color — Colore di sfondo del frontespizio (es. "06386e").
• titlepage-text-color — Colore del testo nel frontespizio (es. "FFFFFF").
• logo — Percorso del logo da includere nel frontespizio.
• header-left — Testo personalizzato nell'header sinistro di ogni pagina.
• footer-left — Testo personalizzato nel footer sinistro di ogni pagina.

Template Customization

Templates are located in the .md/templates/ folder of the project. This folder is created automatically when you open a project with MdExplorer and contains all files needed for export.

.md/templates/
├── pdf/
│   └── eisvogel.tex     (LaTeX template for PDF)
└── word/
    ├── reference.docx   (Word style template)
    ├── minute.docx      (meeting minutes template)
    └── pages/           (additional templates)

Eisvogel variables for PDF

To customize the PDF appearance, you can add Eisvogel-specific variables in the YAML front matter block of your markdown file:

• titlepage — true or false, enables or disables the title page.
• titlepage-color — Title page background color (e.g. "06386e").
• titlepage-text-color — Title page text color (e.g. "FFFFFF").
• logo — Path to the logo to include on the title page.
• header-left — Custom text in the left header of every page.
• footer-left — Custom text in the left footer of every page.

Esempio da Errantia

Nel progetto Errantia, l'analisi funzionale viene esportata in PDF per la review con gli stakeholder. Il documento generato include:

• Frontespizio con logo — Pagina di copertina professionale con titolo, autore, data e logo del progetto.
• Table of contents — Indice automatico generato dal front matter YAML con navigazione ai capitoli.
• Requisiti formattati — Ogni requisito funzionale con ID, descrizione, criteri di accettazione e priorità.
• Diagrammi PlantUML renderizzati — Sequence diagram, use case diagram e class diagram inclusi come immagini ad alta risoluzione.
• Tabelle glossario — Terminologia di dominio formattata in tabelle leggibili e professionali.

Il risultato è un documento professionale generato automaticamente dal markdown versionato in Git. Ogni volta che le specifiche vengono aggiornate, basta riesportare per avere un documento sempre allineato con la versione corrente.

Errantia Example

In the Errantia project, the functional analysis is exported to PDF for stakeholder review. The generated document includes:

• Title page with logo — Professional cover page with title, author, date, and project logo.
• Table of contents — Automatic index generated from YAML front matter with chapter navigation.
• Formatted requirements — Each functional requirement with ID, description, acceptance criteria, and priority.
• Rendered PlantUML diagrams — Sequence diagrams, use case diagrams, and class diagrams included as high-resolution images.
• Glossary tables — Domain terminology formatted in readable and professional tables.

The result is a professional document automatically generated from Git-versioned markdown. Every time specifications are updated, just re-export to have a document always aligned with the current version.