Da Markdown a PDF e ritorno: cosa conserva la conversione di formato
Markdown↔PDF conserva meglio titoli, elenchi e tabelle semplici rispetto ai pixel. Font esatti, paginazione e layout non sopravvivono a un ciclo senza perdite.
Markdown e PDF sono ottimizzati per contratti diversi. Markdown è struttura, amica del controllo di versione. PDF è una descrizione fissa di pagina. Convertire in una direzione e poi tornare indietro è utile, ma non è un ciclo di archiviazione senza perdite.
Da Markdown a PDF: la struttura diventa pagine
Markdown in PDF (POST /api/v1/convert/markdown/pdf) accetta un file .md o uno ZIP che contiene Markdown. I caricamenti che non sono Markdown né ZIP vengono rifiutati. Per l'input .md semplice è richiesto UTF-8. La pipeline converte Markdown in HTML con tabelle, barrato ed elenchi di attività abilitati, avvolge quell'HTML in CSS orientato alla stampa (comprese raccolte di font multi-script e RTL quando rileva l'arabo), poi stampa in PDF con WeasyPrint.
Cosa tende a sopravvivere al passaggio in avanti:
- titoli, paragrafi, elenchi e tabelle Markdown semplici
- testo multi-script che il percorso HTML riesce a impaginare (CJK, latino e altri sistemi coperti dal CSS di stampa)
- un PDF stampabile e condivisibile per flussi di lavoro docs-as-code
Cosa non sopravvive:
- i font del tema del tuo editor come corrispondenza garantita in ogni visualizzatore
- le interruzioni di riga esatte a schermo del file
.md - le funzionalità interattive di Markdown senza equivalente PDF (caselle di spunta live, sezioni comprimibili, link wiki)
Un input ZIP serve a raccogliere Markdown insieme ad asset che il percorso HTML può risolvere accanto al documento. Consideralo una comodità di impacchettamento, non la garanzia che ogni immagine relativa o riferimento CSS appaia identico in ogni visualizzatore.
Da PDF a Markdown: entra lo strato di testo, esce Markdown
PDF in Markdown (POST /api/v1/convert/pdf/markdown) estrae il contenuto testuale in Markdown tramite pdf-inspector. La risposta è text/markdown, scaricata come file .md. I PDF nativi digitali con uno strato di testo pulito si convertono meglio. Le pagine scansionate senza strato di testo producono Markdown vuoto o inutile finché non applichi prima l'OCR, e anche l'OCR su questo sito restituisce Markdown, non uno strato PDF ricercabile.
Aspettati:
- titoli e paragrafi quando le euristiche sulle dimensioni dei font funzionano correttamente (potresti comunque dover rinumerare a mano i livelli
#) - tabelle come tabelle Markdown quando il riconoscimento riesce; le impaginazioni a più colonne possono linearizzarsi in un ordine di lettura diverso
- intestazioni e piè di pagina ripetuti su ogni pagina (da ripulire in un secondo momento)
- immagini ed equazioni sotto forma di immagini che non diventano automaticamente asset locali o LaTeX
Se ti serve prosa pura senza euristiche sui titoli, PDF in testo è l'estrazione più piatta. Le esportazioni a forma di tabella che restituiscono HTTP 204 indicano che non sono stati rilevati blocchi colonnari; vedi Esportazione tabella vuota (204).
Cosa dimostra davvero un ciclo completo
| Sopravvive ragionevolmente | Di solito no |
|---|---|
| Parole, gerarchia dei titoli, struttura degli elenchi | Geometria di pagina perfetta al pixel |
| Tabelle semplici come testo | Font e crenatura esatti |
| Una bozza funzionante per Git o per gli agenti | Paginazione identica alla stampa |
Ripetere il ciclo due volte introduce divergenze. Da Markdown a PDF si rifluisce attraverso WeasyPrint; da PDF a Markdown si ricostruisce la struttura con euristiche di estrazione. Nessuno dei due passaggi conserva un intermedio senza perdite del modello di impaginazione dell'altro formato.
Scegli una direzione canonica
Se il layout di stampa è il tuo sistema di riferimento, conserva il PDF e considera Markdown un'esportazione o un feed per gli agenti. Se ti servono diff, revisione del codice e ingestione da parte degli agenti, preferisci Markdown e considera il PDF come passo di pubblicazione. Non conservare entrambi come «fonti di verità» equivalenti aspettandoti che restino identici dopo le modifiche.
Un ciclo docs-as-code pratico: modifica Markdown in Git → Markdown in PDF per l'artefatto condivisibile → evita PDF→Markdown→PDF come abitudine quotidiana. Usa PDF→Markdown quando hai ereditato un PDF nativo digitale e ti serve testo per un agente, poi considera quel Markdown una nuova bozza, non la garanzia della paginazione originale.
I file cifrati richiedono uno Sblocco autorizzato prima di entrambe le conversioni. I file danneggiati che non si riescono ad analizzare dovrebbero passare prima da Get Info / Ripara. Per gli stessi endpoint via HTTP, vedi Developers.