Ik heb Markdown al jaren elke werkdag geschreven - plugin README's, changelogs, docs voor Toolz.dev, Release Notes voor WP Adminify, de helft van mijn commit-berichten. En het grootste deel van die tijd behandelde ik de renderingstap als magie. Je schrijft sterretjes, GitHub toont vet. prima. Ga verder.
Daarna bouwde ik een docs-sectie die Markdown uit de database haalde en deze in een next.js-pagina maakte, en de magie veranderde in een lijst met zeer specifieke beslissingen die ik moest nemen. Wordt een enkele nieuwe regel een <br>? (Github-opmerkingen zeggen ja. De Markdown-specificatie zegt nee.) doen <div> in de bron renderen als div of als letterlijke tekst? (Hangt ervan af wie het vraagt, en of je de auteur vertrouwt.) Welke klasse gaat op een omheind codeblok, zodat de markeerstift het oppikt? Waarom draait een parser? **bold**text in Bold en een ander laat het met rust?
Niets van dat alles is exotisch. Het is gewoon het spul dat niemand je vertelt, want Markdown ziet er zo eenvoudig uit dat mensen aannemen dat er niets onder zit. Daar zit nogal wat onder. de Markdown naar HTML Converter op Toolz.dev onthult die beslissingen als schakelaars in plaats van ze te verbergen, wat de versie van deze tool is die ik wilde toen ik aan het debuggen was waarom mijn regeleinden bleven verdwijnen.
tl;dr: Markdown is een schrijfformaat; HTML is het weergaveformaat Iets moet de een in de ander compileren De regels die mensen laten struikelen: opeenvolgende regels komen samen in één alinea, tenzij je een regel met twee spaties beëindigt (of een "breaks" optie inschakelt), ruwe HTML wordt doorgegeven of ontsnapt, afhankelijk van de parser's vertrouwensinstellingen, en GitHub's dialect (GFM) voegt tabellen, takenlijsten, doorhalen en bare-URL automatisch linken toe bovenop de gemeenschappelijke markering basislijn. Omheinde code compileert naar
<pre><code class="language-js">, dat is de hook prism, highlight.js en shiki zoeken. de Markdown naar HTML-converter Doet dit allemaal in uw browser, met elke switch zichtbaar.
Wat is Markdown en waarom moet het überhaupt worden geconverteerd?
Markdown is een syntaxis in platte tekst die John Gruber in 2004 publiceerde, met één aangegeven ontwerpdoel: een Markdown-document moet publiceerbaar zijn zoals het is, leesbaar als platte tekst, zonder eruit te zien alsof het is gemarkeerd met tags. Daarom leent de syntaxis van de conventies die mensen al in e-mail gebruikten - sterretjes rond een woord om nadruk te leggen, een streepje onder een kopje, een > voor een citaat.
Het gevolg is dat Markdown geen rendering-indeling is. Niets geeft markdown weer. Browsers tonen HTML en elke plaats die je ooit hebt gehad gezien Markdown gerenderd - GitHub, een statische site, een docs portal, een chat app - draaide eerst een parser en zette HTML op het scherm.
Dus de conversie moet ergens gebeuren. Uw opties zijn ruwweg:
- op de bouwtijd, in een statische site generator of bundel. Prima als de inhoud in je repo leeft.
- Op aanvraag tijd, op een server. Noodzakelijk wanneer inhoud uit een database komt, kostbaar als u het op elk verzoek doet zonder caching.
- in de browser, op het moment dat je het nodig hebt. Dat is wat je wilt als het antwoord op "Ik heb alleen de HTML nodig voor dit ene ding" is een kopieerpaste, geen build-pijplijn.
Dat derde geval komt vaker voor dan het klinkt. Releaseopmerkingen plakken in een CMS-veld dat alleen HTML nodig heeft. Een readme in een e-mailsjabloon krijgen. controleren hoe een doc eruit zal zien voordat u het vastlegt. Een concept dat in obsidiaan is geschreven, omzetten in iets dat je aan een ontwerper kunt overhandigen. Geen van deze rechtvaardigt het bedrading van een parser in een project.
Wat is het verschil tussen CommonMark en GitHub-smaak Markdown?
De originele specificatie van Gruber was een pagina met proza en een Perl-script, en het liet genoeg dubbelzinnigheid achter dat elke implementatie het oneens was met de randgevallen. gemeenschappelijke markering is het antwoord daarop: een strikte, testbare specificatie met een conformance suite van honderden voorbeelden, zodat twee conforme parsers identieke uitvoer produceren voor dezelfde invoer Het definieert de basislijn - koppen, alinea's, nadruk, links, afbeeldingen, lijsten, blockquotes, codeblokken, thematische breaks, backslash escapes, HTML-blokken.
GitHub-smaak Markdown (GFM) is een formele superset van CommonMark, gespecificeerd door GitHub, die de dingen toevoegt waar mensen om bleven vragen:
| gelaatstrek | gemeenschappelijke markering | GFM | syntaxis |
|---|---|---|---|
| tafels | heel weinig | ja | | a | b | met een | --- | --- | scheidingstekenrij |
| Takenlijsten | heel weinig | ja | - [x] done / - [ ] todo |
| doorstrepen | heel weinig | ja | ~~gone~~ |
| Automatische URL's met kale koppelingen | heel weinig | ja | https://toolz.dev Zonder haakjes |
| voetnoten | heel weinig | Ja (Github-extensie) | [^1] |
| Koppen, lijsten, code, nadruk | ja | ja | volkomen hetzelfde |
Als je markdown afkomstig was van een GitHub Readme, een GitLab-wiki, een notie-export of de meeste moderne editors, dan is het GFM. Zet GFM aan in de converter of uw tabellen worden weergegeven als letterlijke pijpen, wat de nummer één is "De converter is kapot' Ondersteuningsvraag Iedereen die een van deze tools ontvangt.
Waarom is mijn regeleinde verdwenen?
Omdat Markdown, volgens de conventies van e-mail in een platte tekst, opeenvolgende niet-lege regels als een enkele alinea behandelt. deze:
Line one
Line two
produceert <p>Line one\nLine two</p>- één alinea, en de nieuwe regel stort in tot een spatie wanneer de browser deze weergeeft. Het is geen bug; het is de specificatie en deze bestaat zodat u uw proza in 80 kolommen in een teksteditor kunt verpakken zonder dat de verpakking in de uitvoer lekt.
Er zijn drie manieren om een echte pauze te krijgen:
- Een lege regel begint een nieuwe alinea. Dit is wat je het grootste deel van de tijd wilt.
- Twee volgplaatsen aan het einde van een lijn produceren een harde breuk -
<br />. Dit is de standaardtruc en het is onzichtbaar in je editor, daarom vinden mensen het gekmakend. - Een backslash Aan het einde van de regel doet hetzelfde in CommonMark, en is op zijn minst zichtbaar.
En dan is er de vierde weg, die de bron van de verwarring is: Veel platforms zetten een "breaks" Waar elke nieuwe lijn een wordt <br />. GitHub-opmerkingen en -problemen doen dit. De meeste chat-apps doen dit. GitHub leesmij-bestanden niet doen. Dus dezelfde tekst wordt anders weergegeven in een GitHub-uitgave en in de readme van dezelfde repository, wat een echt slecht ontwerp is waar we nu allemaal mee vastzitten.
De converter stelt dit bloot als een schakelaar. Als uw bron is geschreven voor een renderer in chatstijl, zet u regeleinden aan. Als het een document is, laat het dan weg en gebruik lege regels zoals de specificatie van plan is.
Hoe wordt omgegaan met rauwe HTML?
Markdown staat inline HTML toe - de originele specificatie zegt expliciet dat alle HTML die je schrijft rechtstreeks doorgaat. Dat is een functie als je de auteur bent (je wilt je <details> blok, jouw <img> met een breedteattribuut, uw anker met een rel), en het is een verplichting als u dat niet bent.
Want als je niet-vertrouwde markdown met HTML-pass-through ingeschakeld maakt, heb je een XSS-kwetsbaarheid. <script>alert(document.cookie)</script> is geldige afwaardering. zo is <img src=x onerror="...">. zo is een <a href="javascript:...">. Een commentaarvak, een gebruikersprofielbio, een openbare wiki - waar vreemden ook noteren Markdown die andere mensen lezen - moeten aan HTML ontsnappen of de uitvoer opschonen met een echte ontsmettingsmiddel (DOMPurify is het gebruikelijke antwoord, en het is juist een echte ontsmettingsmiddel omdat een regex is niet genoeg voor een vijandige invoer).
Deze converter staat standaard op: weglopend RAW-HTML: <div> in uw bron verschijnt als de letterlijke tekst <div> in de uitvoer, precies alsof je had geschreven <div>. U kunt doorvoer inschakelen wanneer de bron van u is. En ongeacht die instelling, de live preview stript <script>, <style>, inline on* Evenementenhandelaars en javascript: URL's voordat het wordt weergegeven - een diepgaande verdedigingsmaatregel, dus iemand anders plakken's README in het voorbeeldvenster kan hun code niet uitvoeren. Dat is een preview-veiligheidsmaatregel, geen ontsmettingsmiddel voor algemene doeleinden: als u een product bouwt dat gebruiker Markdown weergeeft, gebruik dan een speciale ontsmettingsserverzijde en vertrouw geen regex, inclusief de mijne.
Als je een personage moet ontsnappen ten gevolge van Markdown zodat het letterlijk - een asterisk die een asterisk moet blijven, een onderstrepingsteken in een bestandsnaam - een backslash doet het: \*not emphasis\*. En als u entiteiten in de andere richting ruziet, HTML-entiteiten encoder/decoder is het hulpmiddel voor die klus.
Welke HTML moet een goede converter eigenlijk uitzenden?
Semantische, saaie, klassevrije HTML - met één uitzondering.
- Koppen worden
<h1>tentamen<h6>. Met heading-ID's ingeschakeld, krijgt elk ook een slugid, gededupliceerd wanneer twee koppen een titel delen (#setup,#setup-1). Dat is wat maakt#anchorDeep-links werken, en het is wat een generator voor inhoudsopgaven hangt. - Een omheind blok met een inforeeks -
```js- wordt<pre><code class="language-js">. armeDit is de uitzondering.* * de `taal-'Klasse is het conventieprisma, markeer.js en shiki zoeken allemaal, en daarom stoot de converter überhaupt een klasse uit. De converter kleurt je code niet; de markeerstift op je pagina wel, en hij heeft die haak nodig. - Lijsten worden
<ul>/<ol>, en hier is een subtiliteit die het waard is om te weten: a vol Lijst (geen lege regels tussen items) plaatst de tekst direct binnen<li>, terwijl een onsamenhangend Lijst (blanco lijnen tussen items) wikkelt de inhoud van elk item in<p>. Dat is gemeenschappelijk markeergedrag, geen gril, en daarom groeit je lijst plotseling verticale afstand wanneer je een lege regel tussen twee kogels toevoegt. De CSS is niet kapot, de HTML is echt veranderd. - Tabellen worden echt
<table>/<thead>/<tbody>markup, metstyle="text-align:center"op cellen wanneer de scheidingstekenrij gebruikt:---:. - Taaklijsten worden
<input type="checkbox" disabled>Binnen de<li>, en dat is precies wat GitHub uitstraalt.
Inhoudsig-Eerste, geen wrapper-divs, geen gebruiksklassen. Je stylet het van buiten, met een .prose klasse of uw eigen regels, en de markup blijft draagbaar.
Hoe gebruik ik de converter?
Stap 1: Plak de markdown
Drop in een README, een changelog, release notes, een concept Uitvoer updates terwijl u typt - er is geen convert knop, en niets wordt geüpload.
Stap 2: Stel de schakelaars in
GitHub-smaak Aan Als de bron tabellen, taaklijsten of doorhalen heeft (waarschijnlijk wel). Kop-ID's AAN als je ankers wilt. Lijnbreuken Alleen op als de bron is geschreven voor een renderer in chatstijl. Rauwe HTML toestaan Alleen aan als de bron van jou is. Volledig document Aan Als u een volledige HTML5-pagina wilt met DocType, Charset, Viewport en een <title> Genomen uit je eerste <h1>- handig wanneer u het resultaat direct in een browser wilt openen of op een statische host wilt neerzetten.
Stap 3: Controleer het voorbeeld
Schakel over naar het tabblad voor voorbeelden en bevestig de structuur De rij statistieken vertelt u woorden, koppen, links, afbeeldingen, codeblokken en leestijd - handig voor het controleren van een bericht is de lengte die u dacht dat het was voordat u het publiceerde Voor een grondigere telling is de woord teller Doet leesbaarheid en trefwoorddichtheid op dezelfde tekst.
Stap 4: Neem de output
Kopieer de HTML, download deze als een .html bestand, of kopieer de gegenereerde inhoudsopgave - een Markdown geneste lijst die naar elk kopanker linkt, klaar om weer bovenaan uw document te plakken.
Als u het resultaat in een pagina plakt waar bytes van belang zijn, voert u het uit door de html-minifier daarna. De uitgang van de converter is ingesprongen voor de leesbaarheid, niet voor de draad.
Veelvoorkomende gebruiksgevallen
Een readme op een website krijgen
Plugin- en pakketauteurs schrijven een goede readme en hebben vervolgens dezelfde inhoud op een bestemmingspagina nodig. De readme is GFM met tabellen en badges; de landingspagina heeft HTML nodig. Converteer, plak, stijl met uw bestaande CSS. De heading-ID's geven u gratis een zijbalk-TOC.
publiceren naar een CMS dat alleen HTML accepteert
Tal van CMS velden, e-mail platforms en legacy admin panels nemen HTML en niets anders Als je in Markdown - en de meeste mensen die regelmatig schrijven doen - dit is de brug Converteren met Volledig document uit, dus je krijgt het fragment in plaats van een hele pagina en plak het in het veld.
Een Docs-pagina prototyping prototyping
Voordat u inhoud in een Docs-site zet, laat u deze lokaal converteren u de werkelijke kophiërarchie zien en of uw codeomheiningen de juiste taal hebben. een h3 Dat had een h2 is duidelijk in de TOC en onzichtbaar in de bron.
Inhoud controleren Iemand anders schreef
Plak een contribuant' s Markdown, kijk naar de uitgezonden HTML, en je kunt meteen zien of ze echte koppen gebruikten of een regel vetgedrukt hebben om er een te vervalsen - een gewoonte die de documentstructuur en toegankelijkheid vernietigt Schermlezers navigeren op kop; **Big Text** is geen kop, het is een vetgedrukte alinea en de converter laat je dat in één regel output zien.
Een inhoudsopgave extraheren
Lange documenten hebben er een nodig, en het met de hand onderhouden garandeert dat het verouderd wordt. Genereer het uit de koppen, plak het in, regenereer wanneer de koppen veranderen.
Geavanceerd: wat deze parser wel en niet doet
Het is een handgeschreven parser, ruwweg 400 regels, zonder afhankelijkheden - wat opzettelijk is, omdat een Markdown-parser die een afhankelijkheid van 200KB naar een pagina trekt waarvan het hele punt snel is, een slechte transactie is.
gedekt: ATX-koppen (# x) en setExt-koppen (onderstreept met === / ---), alinea's, nadruk en sterk (*, _, **, __), inline-code met backtick-run-matching, omheind code met info-strings, ingesprongen codeblokken, blockquotes met lui voortzetting, geneste lijsten (geordend en ongeordend, strak en los), thematische breaks, links en afbeeldingen met titels, hoekbracket autolinks, e-mailautolinks, backslash-ontsnappingen en de GFM-set: tabellen met uitlijning, taaklijsten, doorsteken, blote-URL autolinks.
Niet gedekt: Links in referentiestijl ([text][ref] met een [ref]: url Definitie elders), voetnoten, definitielijsten en een paar echt obscure CommonMark-hoekgevallen rond HTML-blokkades die alinea's onderbreken. Als u de CommonMark-conformiteitssuite ertegen gebruikt, zal deze niet 100% scoren. Als je een readme, een changelog of een blogpost converteert, zul je het niet merken.
Dat is een eerlijke handel, en dat is de reden waarom de converter onmiddellijk laadt en werkt met het netwerk uit. Gebruik voor inhoudspijplijnen waar u bit-exact commonmark-conformiteit nodig heeft, gebruik markdown-it, remark of cmark In je build, daar zijn ze voor.
FAQ
Hoe converteer ik Markdown naar HTML?
Plak je Markdown in de editor en de HTML verschijnt direct - er is geen converteerknop en geen bestand om te uploaden Schakel GitHub Flavored Markdown in als je bron tabellen of takenlijsten gebruikt, kopieer dan de HTML of download het als een .html bestand Alles draait in je browser, dus ongepubliceerde concepten en interne docs verlaten je apparaat nooit.
Wat is GitHub-smaak Markdown?
GitHub Flavored Markdown (GFM) is een formeel gespecificeerde superset van CommonMark die tabellen, selectievakjes voor takenlijsten, doorhalen met dubbele tildes en automatische koppeling van blote URL's toevoegt. Het is het dialect dat GitHub gebruikt om readme-bestanden en -problemen weer te geven, en het is wat de meeste markdown-editors tegenwoordig uitzenden. Het is standaard ingeschakeld in deze converter.
Waarom is mijn enkele regeleinde verdwenen?
Standaard Markdown verbindt opeenvolgende regels in een enkele alinea; een regeleinde overleeft alleen als u de lijn met twee spaties beëindigt, een achterste streepje gebruikt of een lege regel achterlaat. Als je wilt dat elke nieuwe lijn een wordt <br />, schakel de optie voor regeleinden in - dat is het gedrag dat GitHub-opmerkingen en de meeste chat-apps gebruiken, maar dit is niet wat README-bestanden doen.
Markeert de converter mijn code?
Het zendt de markup uit die een markeerstift nodig heeft, maar kleurt de code zelf niet. Een omheind codeblok getagd met de taal js HALD <pre><code class="language-js">, dat is het klassenconventieprisma, markeer.js en shiki zoeken allemaal. Voeg een van die bibliotheken toe aan de pagina waar u de uitvoer plakt en de markering verschijnt automatisch.
Is raw HTML in mijn markdown bewaard gebleven?
Standaard is het ontsnapt, dus <div> verschijnt als letterlijke tekst in plaats van als een tag Schakel de optie allow-raw-HTML in om tags er rechtstreeks doorheen te laten gaan, wat u wilt als uw Markdown opzettelijk in HTML mixt - a <details> blokkeer, of een afbeelding met attributen. Schakel het alleen in voor bron die u vertrouwt, omdat onbewerkte HTML van een niet-vertrouwde auteur een XSS-vector is.
Is het veilig om Markdown te plakken die ik niet heb geschreven?
Ja. HTML wordt standaard ontsnapt, en de live preview stript bovendien script - en stijltags, inline event handlers en javascript: URL's voordat rendering Niets dat je plakt wordt ergens verzonden Als je een product bouwt dat Markdown van vreemden weergeeft, gebruik dan nog steeds een speciale ontsmettingsmiddel zoals DOMPurify server-side - een preview filter is geen vervanging voor een.
Kan ik een inhoudsopgave genereren uit mijn kopjes?
Ja. Als rubriek-ID's zijn ingeschakeld, krijgt elke kop een slugified, ontdupliceerd anker en bouwt de tool een markdown-inhoudsopgave die naar elk van hen linkt. Kopieer het terug naar de bovenkant van uw document en de links worden opgelost tegen de gegenereerde ID's. regenereer het wanneer uw koppen veranderen in plaats van het met de hand te onderhouden.
Implementeert deze converter volledig CommonMark?
Het implementeert de constructies die mensen daadwerkelijk schrijven - ATX - en setextkoppen, alinea's, nadruk, links, afbeeldingen, autolinks, blockquotes, geneste en losse lijsten, omheinde en ingesprongen code, thematische pauzes, backslash escapes - plus de GFM-extensies Referentie-stijl links, voetnoten en een paar zeldzame CommonMark HTML-blok randgevallen worden niet behandeld Voor bit-exacte conformiteit in een build-pijplijn, gebruik markdown-it, opmerking of cmark.
Verwante hulpmiddelen: Markdown naar HTML · HTML-entiteiten · html-minifier · woord teller · slotenprogramma
Verwante lezing: De toolkit van de webontwikkelaar · Handleiding voor teksthulpmiddelen
