Indsæt to Markdown-dokumenter og se linje for linje, hvad der er ændret. Virker på README-filer, release notes, MDX og dokumenter med frontmatter. Diffen kører i din browser.
Et gratis værktøj, der kører helt i browseren, til at sammenligne to Markdown-dokumenter på kildetekst-niveau. Indsæt en gammel README.md til venstre, den opdaterede til højre, så lyser hver ændret overskrift, listepunkt, link, kodeblok og tabelcelle op. Intet forlader din maskine.
Diffen arbejder tegn for tegn. Markdown er ren tekst, så det er den rigtige primitiv: du ser den faktiske ændring i dokumentkilden, ikke et gæt om, hvordan en renderer ville fortolke den.
Bruger du allerede vores tekst-diff til almindelig prosa, er Markdown-siden den samme motor med tekst rettet mod de tilfælde, der dukker op, når man rent faktisk skriver dokumentation. Til at sammenligne YAML-frontmatter-blokke øverst i Jekyll-, Hugo- eller MkDocs-filer håndterer YAML-siden den indrykningsfølsomme struktur bedre. Stram struktureret data med nøgle/værdi-opslag hører hjemme i JSON-diffen.
Diffen er på tegnniveau. Efter den rå diff flytter en semantisk oprydningspasning markeringerne, så de lander på hele ord, listepunkter og linkmål i stedet for at klippe en inline `code span` midt over eller rive det indledende ## af en overskrift. Tilføjelser farves grønne til højre, sletninger røde til venstre.
Det er en kildetekst-diff, ikke en diff af det renderede output. Det er den rigtige primitiv til Markdown-arbejde, og det vejer mere, end det lyder. To dokumenter, der renderer til identisk HTML, kan have meget forskellige kilder: **fed** mod __fed__, punktopstilling med * mod -, fire mellemrums indrykning mod et tabulatortegn i en indlejret liste. En renderer flader det hele ud i samme output, og du mister signalet. Når du vil vide, om en bidragsyder virkelig kun har rettet en tastefejl, er det kildediffen, der svarer.
Markdown er desuden en familie af dialekter. Den oprindelige specifikation af John Gruber (se daringfireball.net) var bevidst løs, og med tiden trak CommonMark, GitHub Flavored Markdown, Pandoc og MultiMarkdown hver i deres retning. Tabeller findes i GFM og Pandoc, men ikke i CommonMark. Gennemstregning med ~~ og opgavelister med - [ ] er GFM-udvidelser. Diff-værktøjet er ligeglad med dialekt; det viser den rå tekst. Smagen betyder noget, når du begynder at spørge, om et afsnit stadig renderer korrekt under det nye doc-tema, og det er et spørgsmål til din renderer, ikke til diffen.
To tekstpaneler, én diff. Ingen tilmelding, ingen upload, ingen tur til serveren.
Indsæt den gamle version til venstre, den nye til højre. Eller klik på Upload i et af panelerne for at indlæse en .md-, .markdown- eller .mdx-fil. Knappen Eksempel fylder begge sider med en lille README, så du ser diffen arbejde, før du indsætter dit eget indhold.
En fil redigeret på Windows har normalt CRLF-linjeslutninger; en fil fra en Linux-server har LF. En tegn-diff behandler dem som forskellige, hvilket kan male hver linje som ændret. Hvis diffen ser mistænkeligt fuld af rødt og grønt ud, så normalisér først begge filer til den samme linjeslutning i din editor. VS Code viser den aktive linjeslutning i statuslinjen i bunden.
Sletninger vises røde til venstre, tilføjelser grønne til højre. De to paneler scroller synkront. Frontmatter-blokke, kodehegn, tabelrækker og listepunkter er alle bare tekst for diff-motoren, så ændringer inden i dem dukker op på samme måde som ændringer i brødteksten. Ændringstællerne i hver overskrift giver et hurtigt mål for, hvor tung redigeringen var.
Du vil hurtigt se, hvad der er ændret i README.md på en PR-gren i forhold til main, men du vil ikke åbne GitHub, scrolle forbi den renderede forhåndsvisning og klikke "Display the source diff" tre menuer dybt. Indsæt i stedet de to rå filer i dette værktøj. Overskrifter, kodehegn og linkmål kommer tydeligt frem. Nyttigt, når PR'en også rører ved hundrede kildefiler, og dokumentationsændringen forsvinder i støjen.
Release notes går gennem flere redigeringer, før de udkommer. Udkast omrokeres, punkter slås sammen, versionsnumre flytter sig. En diff af de tidligere udgivne RELEASE_NOTES.md mod det nye udkast fanger tabte poster og tilfældige dubletter, hvilket den renderede forhåndsvisning er dårlig til, fordi øjet glider hen over linjer, der ligner hinanden. Diffen gør det også nemt at verificere, at sektionen ## Breaking changes faktisk er vokset mellem releases.
Dit team skriver dokumentation i Markdown i et Git-repo, men det offentlige site genereres af et CMS eller en statisk sitegenerator som MkDocs, Hugo eller Docusaurus. Indimellem driver den udgivne side fra kilden: nogen redigerede den live via CMS-grænsefladen og glemte at pushe tilbage, eller et CI-trin omskrev filen. Eksportér den udgivne side som Markdown, smid den i ét panel, smid repoets .md i det andet, og afvigelsen ligger foran dig på sekunder.
Du sendte et blogindlæg i Markdown til en redaktør. Redaktøren returnerede en markeret version. En diff mellem de to optager feedbacken meget hurtigere end at læse afsnit for afsnit igen, især når redaktøren har omrokeret sektioner eller skrevet din indledning om. Virker lige så godt for ghostwritten indhold, hvor skribenten skal bekræfte, hvilke stemmejusteringer der overlevede redigeringen.
At migrere en Docusaurus- eller Astro-side fra .md til .mdx lyder som en uskyldig operation, indtil du opdager, at nogle imports er flyttet, JSX-komponenter har erstattet det, der før var almindelige Markdown-tabeller, og et par kodehegn nu er pakket ind i egne komponenter. Diff den gamle page.md mod den nye page.mdx fil for fil, og migrationsbeslutningerne bliver til at granske. Samme flow den anden vej, hvis du beslutter, at MDX var en fejl, og vil tilbage til almindelig Markdown.
En kort huskeseddel til de syntaks-grænsetilfælde, dette værktøj oftest får frem i lyset. Dialektkolonnen siger, hvilke smage der faktisk understøtter funktionen, for det er derfra de fleste overraskelser mellem renderere kommer.
| Topic | What this tool does |
|---|---|
| Drift mellem smage | Markdown er en familie. CommonMark er de facto-grundlaget. GFM tilføjer tabeller, opgavelister, gennemstregning og autolinks. Pandoc og MultiMarkdown tilføjer fodnoter, definitionslister og mere. Samme kilde kan rendere meget forskelligt mellem dem. |
| Tabeller | Pipe-afgrænsede tabeller findes i GFM og Pandoc. De er ikke en del af CommonMark eller original-Markdown. Hvis en renderer udskriver rå |-tegn i stedet for celler, er parseren strikt CommonMark, og du har brug for en GFM-kompatibel. |
| Gennemstregning | ~~tekst~~ er en GFM-udvidelse. Original-Markdown og CommonMark understøtter det ikke. Pandoc understøtter det med udvidelsen strikeout aktiv. Hvis din tekst renderes med bogstavelige tildetegn, kender rendereren ikke GFM. |
| Opgavelister | - [ ] todo og - [x] færdig er en GFM-udvidelse. CommonMark renderer dem som almindelige punktopstillinger med bogstavelige klammer. GitHub, GitLab og de fleste moderne doc-sites understøtter dem; almindelige Markdown-processorer gør det typisk ikke. |
| Kodeblokke: med hegn vs indrykkede | Kodeblokke med hegn (tre backticks eller tildetegn, med valgfrit sprog-tag) er CommonMark og understøttes overalt. Den oprindelige specifikation havde kun kodeblokke med fire mellemrums indrykning, som stadig virker, men ikke kan bære et sproghint. At blande de to i én fil er lovligt, men sjusket. |
| Hårde linjeskift | Tre muligheder: afslut en linje med to afsluttende mellemrum, afslut med en backslash \ (CommonMark og GFM, ikke original) eller indsæt en tom linje for et afsnitsskift. Afsluttende mellemrum er usynlige i de fleste editorer, hvilket er grunden til, at hårde linjeskift ofte overlever en diff, ingen menneske opdager. |
| Frontmatter | YAML mellem ----hegn, TOML mellem +++ eller JSON mellem { } helt øverst i filen. Slet ikke en del af Markdown-specifikationen, men allestedsnærværende i Jekyll, Hugo, MkDocs, Docusaurus og Astro. Renderere fjerner det, før de parser brødteksten. |
| Inline-HTML | CommonMark tillader rå HTML-tags inde i Markdown. GFM gør det også, men anvender en HTML-saneringsproces, når der renderes på github.com. Nogle statiske sitegeneratorer sanerer, andre lader HTML passere, og enkelte escaper det. Diffs af sider med indlejrede <div>- eller <iframe>-blokke er almindelige ved migrationsgennemgange. |
Nej. Værktøjet differ Markdown-kildeteksten, ikke den HTML, en renderer ville producere. Det er bevidst. To dokumenter kan rendere til identisk HTML og stadig have kilder med betydelige forskelle, for eksempel punktopstilling skrevet med * mod - eller fed skrevet med ** mod __. En diff på kildeniveau bevarer det signal. Vil du se, hvordan dokumentet renderes, så indsæt det i din sædvanlige forhåndsviser: GitHubs webgrænseflade, VS Code eller din statiske sitegenerator.
En diff af renderet HTML fortæller, hvad læserne kommer til at se. En kildediff fortæller, hvad der rent faktisk er ændret i filen. De svarer på forskellige spørgsmål. For Markdown er kildediffen næsten altid den mest nyttige, fordi den trofast viser forfatterens redigeringer: et overskriftsniveau ændredes fra ## til ###, en kodeblok med hegn skiftede sprog-tag, et relativt link blev absolut. Vil du have sammenligning på HTML-niveau, så kør først begge filer gennem din renderer og diff outputtet.
Selve diffen parser ikke Markdown, så den er ligeglad med, hvilken dialekt du bruger. Tabeller, opgavelister, gennemstregning og autolinks ligner bare tekst. Smagen betyder noget, når du spørger, om dit dokument stadig renderes korrekt. CommonMark er det tætteste, vi har på en basisspecifikation, og GitHub Flavored Markdown er CommonMark plus tabeller, opgavelister, gennemstregning og autolinks. Vælg det, din mål-renderer understøtter.
Frontmatter er bare tekst øverst i filen, indrammet af --- for YAML eller +++ for TOML. Statiske sitegeneratorer som Hugo, Jekyll og MkDocs bruger det til sidemetadata. Diffen behandler blokken som almindelig tekst, så ændringer i title:, date: eller tags: dukker op som enhver anden linje. Hvis din frontmatter er stor og indrykningsfølsom, er vores YAML-diff-side bedre egnet til den blok isoleret.
Ja. MDX er Markdown med indlejrede JSX-komponenter, og JSX er bare mere tekst set fra diffens synsvinkel. Du kan indsætte en .mdx-fil i et af panelerne, og diffen viser ændringer i imports, komponent-props og den omkringliggende Markdown på samme måde, som den gør med .md. Det eneste, værktøjet ikke gør, er at validere, at din JSX kompilerer; det er MDX-kompilatorens opgave. For ren kodegennemgang af JSX-stumperne, indsæt dem i vores tekst-diff.
Linjeslutninger er tegn, så en fil gemt med Windows-stil CRLF og en fil gemt med Unix-stil LF differ forskelligt på hver linje. Hvis dine paneler ser fulde af spøgelsesændringer ud, er det næsten altid årsagen. Løsningen er at normalisere begge filer til samme linjeslutning i din editor, før du indsætter; i VS Code vises den aktive linjeslutning i statuslinjen i bunden og skiftes med ét klik. Gits indstilling core.autocrlf kan også indføre overraskende CRLF-forskelle mellem maskiner.
Din Markdown forlader aldrig din browser. Editoren, diffen og formateren kører alle på din maskine. Ingen analyse af din indtastning, ingen logs, ingen tur til serveren. Baggrundslæsning om selve formatet ligger på Wikipedia, med den nyeste CommonMark-specifikation på spec.commonmark.org/0.31.2 og GitHub-smagen på github.github.com/gfm.