Lim inn to Markdown-dokumenter og se linje for linje hva som er endret. Fungerer på README-filer, release notes, MDX og dokumenter med frontmatter. Diffen kjører i nettleseren din.
Et gratis verktøy som kjører helt i nettleseren for å sammenligne to Markdown-dokumenter på kildetekstnivå. Lim inn en gammel README.md til venstre, den oppdaterte til høyre, og hver endrede overskrift, listepunkt, lenke, kodeblokk og tabellcelle lyser opp. Ingenting forlater maskinen din.
Diffen jobber tegn for tegn. Markdown er ren tekst, så det er den riktige primitiven: du ser den faktiske endringen i dokumentkilden, ikke en gjetning om hvordan en renderer ville tolket den.
Bruker du allerede vår tekst-diff til vanlig prosa, er Markdown-siden samme motor med tekst rettet mot tilfellene som faktisk dukker opp når man skriver dokumentasjon. For å sammenligne YAML-frontmatter-blokker øverst i Jekyll-, Hugo- eller MkDocs-filer håndterer YAML-siden den innrykksfølsomme strukturen bedre. Strengt strukturerte data med nøkkel/verdi-oppslag hører hjemme i JSON-diffen.
Diffen er på tegnnivå. Etter den rå diffen flytter en semantisk opprydningspass markeringene slik at de lander på hele ord, listepunkter og lenkemål i stedet for å klippe et inline `code span` midt i to eller rive løs det innledende ## fra en overskrift. Innsettinger farges grønne til høyre, slettinger røde til venstre.
Det er en kildetekst-diff, ikke en diff av rendert utdata. Det er den riktige primitiven for Markdown-arbeid, og det betyr mer enn det høres ut som. To dokumenter som renderer til identisk HTML kan ha veldig ulike kilder: **fet** mot __fet__, punktlister med * mot -, fire mellomrom innrykk mot et tabulatortegn i en nestet liste. En renderer flater alt dette ut til samme utdata, og du mister signalet. Når du vil vite om en bidragsyter virkelig bare rettet en skrivefeil, er det kildediffen som svarer.
Markdown er dessuten en familie av dialekter. Den opprinnelige spesifikasjonen til John Gruber (se daringfireball.net) var bevisst løs, og over tid trakk CommonMark, GitHub Flavored Markdown, Pandoc og MultiMarkdown hver i sin retning. Tabeller finnes i GFM og Pandoc, men ikke i CommonMark. Gjennomstreking med ~~ og oppgavelister med - [ ] er GFM-utvidelser. Diff-verktøyet bryr seg ikke om dialekt; det viser den rå teksten. Smaken har betydning når du begynner å spørre om et avsnitt fortsatt rendres riktig under det nye doc-temaet, og det er et spørsmål til rendereren din, ikke til diffen.
To tekstpaneler, én diff. Ingen registrering, ingen opplasting, ingen tur til serveren.
Lim inn den gamle versjonen til venstre, den nye til høyre. Eller klikk Last opp i ett av panelene for å åpne en .md-, .markdown- eller .mdx-fil. Knappen Eksempel fyller begge sidene med en liten README slik at du ser diffen i aksjon før du limer inn ditt eget innhold.
En fil redigert på Windows har vanligvis CRLF-linjeslutt; en fil fra en Linux-server har LF. En tegn-diff behandler dem som ulike, noe som kan male hver linje som endret. Hvis diffen ser mistenkelig full av rødt og grønt ut, normaliser først begge filene til samme linjeslutt i editoren. VS Code viser aktiv linjeslutt i statuslinjen nederst.
Slettinger vises røde til venstre, innsettinger grønne til høyre. De to panelene scroller synkront. Frontmatter-blokker, kodegjerder, tabellrader og listepunkter er alle bare tekst for diffmotoren, så endringer inni dem dukker opp på samme måte som endringer i brødteksten. Endringstellerne i hver overskrift gir et raskt mål på hvor tung redigeringen var.
Du vil raskt se hva som er endret i README.md på en PR-gren mot main, men du vil ikke åpne GitHub, scrolle forbi den rendrede forhåndsvisningen og klikke "Display the source diff" tre menyer dypt. Lim heller inn de to rå filene i dette verktøyet. Overskrifter, kodegjerder og lenkemål kommer tydelig fram. Nyttig når PR-en også berører hundre kildefiler og dokumentasjonsendringen forsvinner i støyen.
Release notes går gjennom flere redigeringer før de slippes. Utkast omrokeres, punkter slås sammen, versjonsnumre flytter seg. En diff av tidligere publiserte RELEASE_NOTES.md mot det nye utkastet fanger opp tapte oppføringer og uheldige duplikater, noe den rendrede forhåndsvisningen er dårlig på fordi øyet glir over linjer som ser like ut. Diffen gjør det også enkelt å verifisere at seksjonen ## Breaking changes faktisk har vokst mellom releasene.
Teamet ditt skriver dokumentasjon i Markdown i et Git-repo, men det offentlige nettstedet genereres av et CMS eller en statisk nettstedsgenerator som MkDocs, Hugo eller Docusaurus. Av og til drifter den publiserte siden fra kilden: noen redigerte den live via CMS-grensesnittet og glemte å pushe tilbake, eller et CI-steg skrev om filen. Eksporter den publiserte siden som Markdown, slipp den i ett panel, slipp .md-filen fra repoet i det andre, og avviket ligger foran deg på sekunder.
Du sendte et blogginnlegg til en redaktør i Markdown. Redaktøren sendte tilbake en markert versjon. En diff mellom de to absorberer tilbakemeldingen mye raskere enn å lese avsnitt for avsnitt på nytt, særlig når redaktøren har omrokert seksjoner eller skrevet om innledningen din. Fungerer like godt for spøkelsesskrevet innhold der forfatteren må bekrefte hvilke stemmejusteringer som overlevde redigeringen.
Å migrere et Docusaurus- eller Astro-nettsted fra .md til .mdx høres ut som en uskyldig operasjon, helt til du oppdager at noen imports er flyttet, JSX-komponenter har erstattet det som før var vanlige Markdown-tabeller, og noen kodegjerder nå er pakket inn i egne komponenter. Diff den gamle page.md mot den nye page.mdx fil for fil, og migrasjonsvalgene blir mulige å gjennomgå. Samme flyt motsatt vei dersom du bestemmer at MDX var en feil og vil tilbake til vanlig Markdown.
En kort huskelapp til syntaks-grensetilfellene dette verktøyet oftest får fram. Dialektkolonnen sier hvilke smaker som faktisk støtter funksjonen, for det er der de fleste overraskelsene mellom renderere kommer fra.
| Topic | What this tool does |
|---|---|
| Drift mellom smaker | Markdown er en familie. CommonMark er de facto-grunnlaget. GFM legger til tabeller, oppgavelister, gjennomstreking og autolenker. Pandoc og MultiMarkdown legger til fotnoter, definisjonslister og mer. Samme kilde kan rendre svært ulikt mellom dem. |
| Tabeller | Pipe-avgrensede tabeller finnes i GFM og Pandoc. De er ikke en del av CommonMark eller original-Markdown. Hvis en renderer skriver ut rå |-tegn i stedet for celler, er parseren strengt CommonMark og du trenger en GFM-kompatibel. |
| Gjennomstreking | ~~tekst~~ er en GFM-utvidelse. Original-Markdown og CommonMark støtter det ikke. Pandoc støtter det med utvidelsen strikeout aktiv. Hvis teksten din rendrer med bokstavelige tildetegn, kjenner ikke rendereren GFM. |
| Oppgavelister | - [ ] todo og - [x] ferdig er en GFM-utvidelse. CommonMark rendrer dem som vanlige punktlister med bokstavelige hakeparenteser. GitHub, GitLab og de fleste moderne doc-nettsteder støtter dem; vanlige Markdown-prosessorer gjør det vanligvis ikke. |
| Kodeblokker: med gjerde vs innrykk | Kodeblokker med gjerde (tre backticks eller tildetegn, med valgfritt språkmerke) er CommonMark og støttes overalt. Den opprinnelige spesifikasjonen hadde bare kodeblokker med fire mellomroms innrykk; de fungerer fortsatt, men kan ikke bære et språkhint. Å blande de to i én fil er lovlig, men rotete. |
| Harde linjeskift | Tre alternativer: avslutt en linje med to mellomrom på slutten, avslutt med en backslash \ (CommonMark og GFM, ikke original) eller sett inn en tom linje for avsnittsskift. Avsluttende mellomrom er usynlige i de fleste editorer, og det er derfor harde linjeskift ofte overlever en diff ingen menneske ser. |
| Frontmatter | YAML mellom ----gjerder, TOML mellom +++ eller JSON mellom { } helt øverst i filen. Ikke en del av Markdown-spesifikasjonen i det hele tatt, men allestedsnærværende i Jekyll, Hugo, MkDocs, Docusaurus og Astro. Renderere fjerner det før de parser brødteksten. |
| Inline-HTML | CommonMark tillater rå HTML-tagger inni Markdown. GFM gjør det også, men bruker en HTML-saneringsprosess ved rendering på github.com. Noen statiske nettstedsgeneratorer sanerer, andre slipper HTML gjennom, og noen få escaper det. Differ av sider med innebygde <div>- eller <iframe>-blokker er vanlige ved migrasjonsrevisjoner. |
Nei. Verktøyet differ Markdown-kildeteksten, ikke HTML-en en renderer ville produsert. Det er bevisst. To dokumenter kan rendre til identisk HTML og likevel ha kilder med vesentlige forskjeller, for eksempel punktlister skrevet med * mot - eller fet skrevet med ** mot __. En diff på kildenivå bevarer det signalet. Vil du se hvordan dokumentet rendres, lim det inn i din vanlige forhåndsviser: GitHubs nettgrensesnitt, VS Code eller den statiske nettstedsgeneratoren din.
En diff av rendret HTML forteller hva leserne kommer til å se. En kildediff forteller hva som faktisk ble endret i filen. De svarer på ulike spørsmål. For Markdown er kildediffen nesten alltid den mest nyttige fordi den trofast viser forfatterens redigeringer: et overskriftsnivå endret seg fra ## til ###, en kodeblokk med gjerde byttet språkmerke, en relativ lenke ble absolutt. Vil du ha sammenligning på HTML-nivå, kjør først begge filene gjennom rendereren og diff utdataen.
Selve diffen parser ikke Markdown, så den er likegyldig til hvilken dialekt du bruker. Tabeller, oppgavelister, gjennomstreking og autolenker ser bare ut som tekst. Smaken har betydning når du spør om dokumentet ditt fortsatt rendres riktig. CommonMark er det nærmeste vi har en basisspesifikasjon, og GitHub Flavored Markdown er CommonMark pluss tabeller, oppgavelister, gjennomstreking og autolenker. Velg det målrendereren din støtter.
Frontmatter er bare tekst øverst i filen, rammet inn av --- for YAML eller +++ for TOML. Statiske nettstedsgeneratorer som Hugo, Jekyll og MkDocs bruker det til sidemetadata. Diffen behandler blokken som vanlig tekst, så endringer i title:, date: eller tags: dukker opp som hvilken som helst annen linje. Hvis frontmatteren er stor og innrykksfølsom, er YAML-diff-siden vår bedre egnet for den blokken isolert.
Ja. MDX er Markdown med innebygde JSX-komponenter, og JSX er bare mer tekst sett fra diffens synsvinkel. Du kan lime inn en .mdx-fil i et av panelene, og diffen løfter fram endringer i imports, komponent-props og omkringliggende Markdown på samme måte som med .md. Det eneste verktøyet ikke gjør, er å validere at JSX-en din kompilerer; det er MDX-kompilatorens jobb. For ren kodegjennomgang av JSX-bitene, lim dem inn i tekst-diffen vår.
Linjeslutt er tegn, så en fil lagret med Windows-stil CRLF og en fil lagret med Unix-stil LF vil differe ulikt på hver linje. Hvis panelene dine ser fulle av spøkelsesendringer ut, er det nesten alltid årsaken. Løsningen er å normalisere begge filene til samme linjeslutt i editoren før du limer inn; i VS Code vises aktiv linjeslutt i statuslinjen nederst og byttes med ett klikk. Gits innstilling core.autocrlf kan også gi overraskende CRLF-forskjeller mellom maskiner.
Markdown-en din forlater aldri nettleseren din. Editoren, diffen og formateren kjører alle på maskinen din. Ingen analyse av inndataene dine, ingen logger, ingen tur til serveren. Bakgrunnslesning om selve formatet finnes på Wikipedia, med den nyeste CommonMark-spesifikasjonen på spec.commonmark.org/0.31.2 og GitHub-smaken på github.github.com/gfm.