142 lines
8.5 KiB
Markdown
142 lines
8.5 KiB
Markdown
# Markdown Converter
|
|
|
|
<!-- Inserisci qui uno screenshot dell'applicazione in funzione -->
|
|
|
|
|
|
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:**
|
|
```bash
|
|
git clone <URL_DEL_TUO_REPOSITORY>
|
|
cd MarkdownConverter
|
|
```
|
|
|
|
2. **Crea un ambiente virtuale (raccomandato):**
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # Su Windows: venv\Scripts\activate
|
|
```
|
|
|
|
3. **Installa le librerie Python:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
git clone <YOUR_REPOSITORY_URL>
|
|
cd MarkdownConverter
|
|
```
|
|
|
|
2. **Create a virtual environment (recommended):**
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
```
|
|
|
|
3. **Install Python libraries:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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. |