Incolla due documenti Markdown e vedi cosa è cambiato riga per riga. Funziona su file README, note di rilascio, MDX e documenti con frontmatter. Il diff gira nel tuo browser.
Uno strumento gratuito, eseguito nel browser, per confrontare due documenti Markdown a livello di testo sorgente. Incolla un vecchio README.md a sinistra, quello aggiornato a destra, e ogni titolo, elemento di lista, link, blocco di codice e cella di tabella modificato si illumina. Niente lascia il tuo dispositivo.
Il diff lavora carattere per carattere. Markdown è testo semplice, quindi questa è la primitiva giusta: vedi la modifica letterale nel sorgente del documento, non un'ipotesi su come la interpreterebbe un renderer.
Se usi già il nostro diff di testo per la prosa generica, la pagina Markdown è lo stesso motore con testi pensati per i casi che capitano davvero quando si scrive documentazione. Per confrontare i blocchi frontmatter in YAML in cima ai file di Jekyll, Hugo o MkDocs, la pagina YAML gestisce meglio la struttura sensibile all'indentazione. I dati strutturati rigorosi con ricerche per chiave/valore stanno meglio nel diff JSON.
Il diff è a livello di carattere. Dopo il diff grezzo, una passata di pulizia semantica sposta gli evidenziatori in modo che cadano su parole intere, elementi di lista e destinazioni di link, invece di spezzare a metà uno `code span` inline o staccare i ## iniziali da un titolo. Le inserzioni si colorano di verde a destra, le cancellazioni di rosso a sinistra.
È un diff sul testo sorgente, non sull'output renderizzato. È la primitiva giusta per il lavoro su Markdown e conta più di quanto sembri. Due documenti che renderizzano nello stesso HTML possono avere sorgenti molto diversi: **grassetto** contro __grassetto__, elenchi puntati con * contro -, indentazione a quattro spazi contro tab in una lista annidata. Un renderer schiaccia tutto questo nello stesso output e perderesti il segnale. Quando vuoi sapere se un contributor ha davvero corretto solo un refuso, è il diff di sorgente a rispondere.
Markdown è anche una famiglia di dialetti. La specifica originale di John Gruber (vedi daringfireball.net) era volutamente lasca, e nel tempo CommonMark, GitHub Flavored Markdown, Pandoc e MultiMarkdown hanno tirato ognuno in una direzione diversa. Le tabelle esistono in GFM e Pandoc ma non in CommonMark. Il barrato con ~~ e le liste di task con - [ ] sono estensioni di GFM. Lo strumento di diff non si cura del dialetto; mostra il testo grezzo. Il sapore conta quando inizi a chiederti se un paragrafo viene ancora renderizzato bene con il nuovo tema della docs, e questa è una domanda per il renderer, non per il diff.
Due pannelli di testo, un diff. Niente registrazione, niente upload, niente andata e ritorno al server.
Incolla la versione vecchia a sinistra, la nuova a destra. Oppure clicca Carica in uno dei pannelli per aprire un file .md, .markdown o .mdx. Il pulsante Esempio riempie entrambi i lati con un piccolo README così vedi il diff in azione prima di incollare i tuoi contenuti.
Un file modificato su Windows di solito ha fine riga CRLF; uno preso da un server Linux ha LF. Un diff a livello di carattere li tratta come diversi e può colorare ogni riga come modificata. Se il diff sembra sospettosamente pieno di rosso e verde, normalizza prima entrambi i file allo stesso fine riga nel tuo editor. VS Code mostra il fine riga attivo nella barra di stato in basso.
Le cancellazioni appaiono in rosso a sinistra, le inserzioni in verde a destra. I due pannelli scorrono insieme. Blocchi di frontmatter, recinti di codice, righe di tabella ed elementi di lista sono tutti solo testo per il motore di diff, quindi i cambiamenti al loro interno emergono come quelli del corpo del testo. I contatori di modifiche in ogni intestazione danno una misura rapida di quanto è stato pesante l'editing.
Vuoi una lettura rapida di cosa è cambiato in README.md su un branch di PR rispetto a main, ma non vuoi aprire GitHub, scorrere oltre la preview renderizzata e cliccare "Display the source diff" tre menu più in basso. Incolla i due file grezzi in questo strumento. Titoli, recinti di codice e destinazioni dei link emergono con chiarezza. Utile quando la PR tocca anche cento file di sorgente e la modifica della docs si perde nel rumore.
Le note di rilascio passano per più revisioni prima di uscire. Le bozze vengono riordinate, i punti accorpati, i numeri di versione si spostano. Differenziare le precedenti RELEASE_NOTES.md pubblicate con la nuova bozza intercetta voci sparite e duplicati accidentali, cosa in cui la preview renderizzata è scarsa perché l'occhio scivola sulle righe simili. Il diff rende anche facile verificare se la sezione ## Breaking changes sia davvero cresciuta tra una versione e l'altra.
Il tuo team scrive la docs in Markdown in un repo Git, ma il sito pubblico è generato da un CMS o da un generatore statico come MkDocs, Hugo o Docusaurus. Ogni tanto la pagina pubblicata si scosta dalla fonte: qualcuno ha modificato la pagina live dalla UI del CMS senza ripushare, oppure uno step di CI ha riscritto il file. Esporta la pagina pubblicata come Markdown, mettila in un pannello, metti il .md del repo nell'altro, e lo scostamento ti compare davanti in pochi secondi.
Hai mandato un post sul blog in Markdown a un editor. L'editor ti ha restituito una versione marcata. Un diff tra le due assorbe il feedback molto più in fretta della rilettura paragrafo per paragrafo, soprattutto quando l'editor ha riordinato le sezioni o riscritto la tua introduzione. Funziona altrettanto bene per contenuti scritti da terzi quando l'autore vuole verificare quali aggiustamenti di voce siano sopravvissuti al passaggio editoriale.
Migrare un sito Docusaurus o Astro da .md a .mdx sembra un'operazione innocua, finché non scopri che alcuni import si sono spostati, qualche componente JSX ha sostituito tabelle che prima erano in Markdown puro e alcuni recinti di codice sono ora avvolti in componenti personalizzati. Diffa la vecchia page.md contro la nuova page.mdx file per file e le scelte di migrazione diventano revisionabili. Stesso flusso al contrario se decidi che MDX è stato un errore e vuoi tornare al Markdown puro.
Un riassunto breve dei casi limite di sintassi che questo strumento porta a galla più spesso. La colonna del dialetto dice quali sapori supportano davvero la funzione, perché è da lì che arrivano la maggior parte delle sorprese tra renderer.
| Topic | What this tool does |
|---|---|
| Drift fra sapori | Markdown è una famiglia. CommonMark è la base di fatto. GFM aggiunge tabelle, liste di task, barrato e autolink. Pandoc e MultiMarkdown aggiungono note a piè di pagina, liste di definizioni e altro. La stessa sorgente può renderizzare in modo molto diverso tra di loro. |
| Tabelle | Le tabelle delimitate da pipe esistono in GFM e Pandoc. Non fanno parte di CommonMark né del Markdown originale. Se un renderer stampa caratteri | grezzi invece di celle, il parser è CommonMark stretto e ti serve uno compatibile con GFM. |
| Barrato | ~~testo~~ è un'estensione di GFM. Markdown originale e CommonMark non lo supportano. Pandoc lo supporta con l'estensione strikeout attiva. Se il tuo testo viene renderizzato con tilde letterali, il renderer non riconosce GFM. |
| Liste di task | - [ ] todo e - [x] fatto sono un'estensione di GFM. CommonMark le rende come semplici punti elenco con parentesi letterali. GitHub, GitLab e la maggior parte dei siti di docs moderni le supportano; i processori Markdown standard di solito no. |
| Blocchi di codice: recintati vs indentati | I blocchi recintati (tre backtick o tilde, con tag di linguaggio opzionale) sono CommonMark e supportati ovunque. La specifica originale aveva solo blocchi indentati di quattro spazi, che funzionano ancora ma non possono trasportare un suggerimento di linguaggio. Mischiare i due in un file è legale ma confuso. |
| Interruzioni di riga forzate | Tre opzioni: terminare una riga con due spazi finali, terminarla con una backslash \ (CommonMark e GFM, non originale) o inserire una riga vuota per un cambio di paragrafo. Gli spazi finali sono invisibili nella maggior parte degli editor, ed è per questo che le interruzioni forzate sopravvivono spesso a un diff che nessun umano nota. |
| Frontmatter | YAML tra recinti ---, TOML tra +++ o JSON tra { } in cima al file. Non fa parte della specifica Markdown ma è ovunque in Jekyll, Hugo, MkDocs, Docusaurus e Astro. I renderer lo tolgono prima di parsare il corpo. |
| HTML inline | CommonMark consente tag HTML grezzi dentro al Markdown. Anche GFM lo fa, ma applica un sanitizzatore HTML quando renderizza su github.com. Alcuni generatori statici sanitizzano, altri lasciano passare l'HTML, qualcuno lo escapa. I diff di pagine con blocchi <div> o <iframe> incorporati sono frequenti negli audit di migrazione. |
No. Lo strumento fa il diff sul testo sorgente del Markdown, non sull'HTML che produrrebbe un renderer. È intenzionale. Due documenti possono renderizzare nello stesso HTML e avere comunque sorgenti con differenze importanti, per esempio elenchi scritti con * contro - o grassetto scritto con ** contro __. Il diff a livello di sorgente preserva questo segnale. Se vuoi vedere come il documento renderizza, incollalo nel tuo previewer abituale: la UI web di GitHub, VS Code o il tuo generatore statico.
Un diff di HTML renderizzato ti dice cosa vedranno i lettori. Un diff di sorgente ti dice cosa è stato davvero cambiato nel file. Rispondono a domande diverse. Per Markdown il diff di sorgente è quasi sempre il più utile perché mostra fedelmente le modifiche dell'autore: un livello di titolo passato da ## a ###, un blocco di codice recintato che ha cambiato il tag di linguaggio, un link relativo diventato assoluto. Se vuoi un confronto a livello HTML, passa entrambi i file dal tuo renderer e poi diffa l'output.
Il diff in sé non parsa il Markdown, quindi non gli importa quale dialetto usi. Tabelle, liste di task, barrato e autolink sembrano semplice testo. Il sapore conta quando ti chiedi se il tuo documento renderizza ancora correttamente. CommonMark è la cosa più vicina a una specifica di base, e GitHub Flavored Markdown è CommonMark più tabelle, liste di task, barrato e autolink. Scegli quello che il tuo renderer di destinazione supporta.
Il frontmatter è solo testo in cima al file, racchiuso da --- per YAML o +++ per TOML. Generatori statici come Hugo, Jekyll e MkDocs lo usano per i metadati di pagina. Il diff tratta il blocco come testo qualsiasi, quindi modifiche a title:, date: o tags: appaiono come ogni altra riga. Se il tuo frontmatter è grande e sensibile all'indentazione, la nostra pagina di diff YAML è più adatta a quel blocco preso da solo.
Sì. MDX è Markdown con componenti JSX incorporati, e il JSX dal punto di vista del diff è solo altro testo. Puoi incollare un file .mdx in uno dei pannelli e il diff farà emergere modifiche agli import, alle prop dei componenti e al Markdown circostante come fa con .md. L'unica cosa che lo strumento non fa è validare che il tuo JSX compili; quello è compito del compilatore MDX. Per una revisione pura del codice JSX, incollalo nel nostro diff di testo.
I fine riga sono caratteri, quindi un file salvato con CRLF stile Windows e uno con LF stile Unix risultano diversi a ogni riga. Se i pannelli sembrano pieni di modifiche fantasma, è quasi sempre questa la causa. La soluzione è normalizzare entrambi i file allo stesso fine riga nel tuo editor prima di incollare; in VS Code il fine riga attivo è mostrato nella barra di stato in basso e si cambia con un clic. Anche l'impostazione core.autocrlf di Git può introdurre differenze CRLF a sorpresa tra macchine diverse.
Il tuo Markdown non lascia mai il browser. Editor, diff e formattatore girano tutti sulla tua macchina. Niente analytics sul tuo input, niente log, niente andata e ritorno al server. Per una lettura di sfondo sul formato c'è materiale su Wikipedia, con la specifica CommonMark più recente su spec.commonmark.org/0.31.2 e il sapore di GitHub su github.github.com/gfm.