SXXXXXXX_MarkdownConverter/README.md

Markdown Converter

Un'applicazione desktop per convertire file Markdown in documenti DOCX e PDF professionali, utilizzando un potente sistema di template e profili per automatizzare la creazione di documenti standardizzati.

---

ITALIANO

🇮🇹 Panoramica

Markdown Converter è uno strumento progettato per semplificare e standardizzare la creazione di documenti tecnici e manuali. Invece di gestire manualmente la formattazione in un word processor, puoi scrivere i contenuti in semplice Markdown e lasciare che l'applicazione si occupi di applicare un template DOCX complesso, sostituendo dinamicamente i segnaposto (placeholder) con i valori specificati.

L'applicazione è costruita attorno a un sistema di profili, che permette di salvare diverse configurazioni (template + valori dei placeholder) per diversi progetti, massimizzando la riusabilità e riducendo gli errori.

Caratteristiche Principali

• Gestione a Profili: Crea, rinomina ed elimina profili nominativi. Ogni profilo lega un set di valori a un template specifico, perfetto per gestire più progetti o clienti con lo stesso layout.
• Scansione Dinamica dei Placeholder: L'applicazione scansiona automaticamente il template .docx selezionato e genera dinamicamente i campi di input per ogni placeholder %%PLACEHOLDER_NAME%% trovato.
• Placeholder Strutturali e Dinamici: Distingue tra placeholder da riempire manualmente (es. %%DOC_PROJECT%%) e placeholder strutturali gestiti automaticamente (es. %%REVISION_RECORD%%, %%DOC_TOC%%), che vengono mostrati nella GUI a scopo informativo.
• Triplo Percorso di Conversione:
  1. MD → DOCX: Converte il Markdown in un file DOCX formattato, usando il template e i valori del profilo.
  2. MD → PDF (Diretto): Crea un PDF "pulito" direttamente dal Markdown, ideale per bozze rapide.
  3. DOCX → PDF (Alta Fedeltà): Converte il file DOCX generato in un PDF. Questo permette una revisione manuale in Word/LibreOffice prima della "cristallizzazione" finale in PDF, garantendo la massima fedeltà del layout.
• Rilevamento Automatico dei Convertitori: Per la conversione DOCX → PDF, l'applicazione cerca prima Microsoft Word e, se non lo trova, ripiega automaticamente su LibreOffice.
• Nomi File Dinamici: Suggerisce nomi di file di output standardizzati e "sanificati" basati sui valori dei placeholder (progetto, numero, revisione, ecc.).
• Persistenza dei Dati: Salva l'ultimo profilo usato, l'ultimo file Markdown e tutti i valori inseriti per ogni profilo, rendendo il lavoro tra una sessione e l'altra più rapido ed efficiente.

Installazione e Avvio

Prerequisiti

1. Python 3.8+
2. Dipendenze esterne (per una funzionalità completa):
   • wkhtmltopdf: Necessario per la conversione diretta da Markdown a PDF. Assicurati che sia installato e, se non è nel PATH di sistema, il percorso è configurato nel codice (core.py).
   • Microsoft Word o LibreOffice: Necessario per la conversione ad alta fedeltà da DOCX a PDF.

Setup

1. Clona il repository:

   git clone <URL_DEL_TUO_REPOSITORY>
   cd MarkdownConverter
   

2. Crea un ambiente virtuale (raccomandato):

   python -m venv venv
   source venv/bin/activate  # Su Windows: venv\Scripts\activate
   

3. Installa le librerie Python:

   pip install -r requirements.txt
   

   (Assicurati di creare un file requirements.txt con le seguenti librerie: ttkbootstrap, pypandoc, python-docx, docx2pdf, pdfkit, markdown)

4. Avvia l'applicazione:

   python -m markdownconverter
   

Flusso di Lavoro Consigliato

1. Crea un Profilo: Clicca su "Manage..." e poi "New...". Assegna un nome al profilo (es. "Manuale Progetto X") e seleziona il file template .docx che vuoi associare.
2. Seleziona il Profilo: Scegli il profilo appena creato dal menu a tendina "Active Profile".
3. Compila i Dati: La GUI mostrerà automaticamente tutti i placeholder trovati nel template. Inserisci i valori desiderati.
4. Seleziona il File Sorgente: Seleziona il file .md da convertire.
5. Converti:
   • Clicca "MD -> DOCX". I valori che hai inserito verranno salvati automaticamente nel profilo.
   • Apri il DOCX generato, aggiorna l'indice dei contenuti e fai le modifiche finali.
   • Clicca "DOCX -> PDF" per creare il documento finale.

---

ENGLISH

🇬🇧 Overview

Markdown Converter is a tool designed to simplify and standardize the creation of technical documents and manuals. Instead of manually handling formatting in a word processor, you can write content in plain Markdown and let the application apply a complex DOCX template, dynamically replacing placeholders with your specified values.

The application is built around a profile system, allowing you to save different configurations (template + placeholder values) for various projects, maximizing reusability and reducing errors.

Key Features

• Profile-based Management: Create, rename, and delete named profiles. Each profile links a set of values to a specific template, perfect for managing multiple projects or clients with the same layout.
• Dynamic Placeholder Scanning: The application automatically scans the selected .docx template and dynamically generates input fields for every %%PLACEHOLDER_NAME%% it finds.
• Structural & Dynamic Placeholders: It distinguishes between manually-filled placeholders (e.g., %%DOC_PROJECT%%) and automatically-managed structural placeholders (e.g., %%REVISION_RECORD%%, %%DOC_TOC%%), which are displayed for informational purposes.
• Triple Conversion Workflow:
  1. MD → DOCX: Converts Markdown to a fully formatted DOCX file using the profile's template and values.
  2. MD → PDF (Direct): Creates a clean PDF directly from Markdown, ideal for quick drafts.
  3. DOCX → PDF (High-Fidelity): Converts the generated DOCX file to a PDF. This allows for a final manual review in Word/LibreOffice before "freezing" the document, ensuring maximum layout fidelity.
• Automatic Converter Detection: For the DOCX → PDF conversion, the application first tries to use Microsoft Word and automatically falls back to LibreOffice if Word is not found.
• Dynamic Filenames: Suggests standardized and sanitized output filenames based on placeholder values (project, number, revision, etc.).
• Data Persistence: Saves the last-used profile, the last Markdown file, and all entered values for each profile, making work between sessions faster and more efficient.

Installation & Setup

Prerequisites

1. Python 3.8+
2. External Dependencies (for full functionality):
   • wkhtmltopdf: Required for the direct Markdown to PDF conversion. Ensure it's installed and, if not in the system PATH, its path is configured in the code (core.py).
   • Microsoft Word or LibreOffice: Required for the high-fidelity DOCX to PDF conversion.

Setup

1. Clone the repository:

   git clone <YOUR_REPOSITORY_URL>
   cd MarkdownConverter
   

2. Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install Python libraries:

   pip install -r requirements.txt
   

   (Make sure to create a requirements.txt file containing at least: ttkbootstrap, pypandoc, python-docx, docx2pdf, pdfkit, markdown)

4. Run the application:

   python -m markdownconverter
   

Recommended Workflow

1. Create a Profile: Click "Manage..." and then "New...". Give the profile a name (e.g., "Project X Manual") and select the associated .docx template file.
2. Select the Profile: Choose the newly created profile from the "Active Profile" dropdown menu.
3. Fill in the Data: The GUI will automatically display all placeholders found in the template. Fill in the desired values.
4. Select the Source File: Choose the .md file you want to convert.
5. Convert:
   • Click "MD -> DOCX". The values you entered will be automatically saved to the profile.
   • Open the generated DOCX, update the table of contents, and make any final manual adjustments.
   • Click "DOCX -> PDF" to create the final, polished document.