Zet HTML om in nette Markdown

Zo zet je HTML om in Markdown

1. Voeg je HTML toe. Plak markup in het vak, open een lokaal .html-bestand of kopieer een deel van een webpagina en plak het: met rijk plakken aan haalt de converter de opgemaakte HTML uit je klembord in plaats van de platte tekst.
2. Stel een basis-URL in als links relatief zijn. Markup uit de bron van een pagina heeft vaak links als /docs/setup. Voer het paginaadres in en elke relatieve link en afbeelding wordt absoluut.
3. Kies je Markdown-stijl. De standaardinstellingen (ATX-koppen, streepjes als opsommingsteken, omheinde code, inline links, GFM aan) passen bij GitHub, GitLab, Obsidian, de meeste generatoren voor statische sites en AI-tools.
4. Kopieer of download. Het resultaat werkt bij terwijl je typt. Kopieer het naar het klembord of bewaar het als .md-bestand, vernoemd naar de eerste kop.

Wat er wordt omgezet, element voor element

Markdown heeft een veel kleinere woordenschat dan HTML, dus de echte taak van een converter is beslissen wat elk element wordt. Dit levert de tool op:

• Koppen <h1>–<h6> worden # tot ######. De setext-stijl onderstreept alleen H1 en H2, omdat de syntaxis niet meer kent; H3 en lager gebruiken nog steeds #.
• Vet en cursief (<strong>, <b>, <em>, <i>) gebruiken de scheidingstekens die je kiest.
• Links worden [tekst](url "titel"), of genummerde verwijzingen die aan het einde van het document worden verzameld als je verwijzingslinks kiest. Links die scripts uitvoeren (javascript:) of data:-inhoud dragen, worden tot hun tekst teruggebracht.
• Afbeeldingen worden ![alt](src). Lazy-loaded afbeeldingen die het echte adres in data-src bewaren, worden ook opgepikt. Inline data:-afbeeldingen vallen weg omdat een base64-blok een Markdown-bestand onleesbaar maakt.
• Lijsten, ook die meerdere niveaus diep genest zijn, springen in onder hun bovenliggende item. Genummerde lijsten behouden hun start-getal, dus een lijst die bij 4 begint, begint nog steeds bij 4.
• Citaten worden >-regels, geneste citaten inbegrepen.
• Code: inline <code> wordt backticks; <pre>-blokken worden omheinde blokken met de taal als die is opgegeven (zie hieronder).
• Tabellen worden GFM-pipe-tabellen. Details en grenzen staan in de volgende sectie.
• Doorhaling en takenlijsten: <del>, <s> en <strike> worden ~~tekst~~; lijstitems die met een selectievakje beginnen worden - [ ] of - [x].
• Volledig verwijderd: <script>, <style>, <noscript>, <template>, iframes, embeds, SVG en canvas. Opmaakwrappers als <div> en <span> worden uitgepakt en alleen hun tekst blijft, precies wat Markdown kleiner en leesbaarder maakt dan de HTML waaruit het komt.

Tabellen: wat Markdown wel en niet kan bevatten

De specificatie van GitHub Flavored Markdown (Engels) definieert een tabel als een koprij, een scheidingsrij van streepjes en inhoudsrijen. Drie regels uit de specificatie bepalen hoe HTML-tabellen worden omgezet:

• Een koprij is verplicht. Veel HTML-tabellen, vooral uit spreadsheets of oude cms-pagina’s, hebben helemaal geen <th>-cellen. Zo kunnen ze geen pipe-tabel worden, dus de converter maakt standaard van de eerste rij de kop. Haal het vinkje weg als je die tabellen liever als HTML houdt.
• Blokinhoud kan niet in een cel staan. De specificatie zegt dat blokelementen niet in een tabel mogen worden ingevoegd, dus alinea’s en regeleinden in een cel worden op één regel samengevoegd. Lijsten in cellen verliezen hun structuur; bevat een tabel rijke inhoud, overweeg dan hem als HTML te houden.
• Een letterlijke pipe moet worden ge-escaped. Een | in een cel zou een nieuwe kolom starten, dus de converter schrijft hem als \|, wat de specificatie overal in een cel toestaat, ook in codefragmenten.

Samengevoegde cellen worden deels ondersteund: een cel met colspan="3" wordt gevolgd door twee lege cellen zodat de kolommen op één lijn blijven. Rijsamenvoegingen hebben geen Markdown-equivalent en worden niet nagebootst. Een <caption> wordt als eigen alinea boven de tabel gezet, en kolomuitlijning uit align-attributen wordt :--, :-: of --: in de scheidingsrij.

Codeblokken en syntaxismarkering

Omheinde codeblokken kunnen na de openende omheining een infostring dragen, zoals ```python, die weergaves gebruiken om de code te kleuren. De converter zoekt de taal op de plekken waar markeerders haar neerzetten: language-*- en lang-*-klassen (Prism, highlight.js en de meeste Markdown-weergaven), de highlight-source-*-wrapper van GitHub en data-lang- of data-language-attributen. Een <pre> zonder binnenste <code>-element wordt nog steeds als codeblok behandeld en niet als ge-escapete tekst.

De codetekst wordt letterlijk overgenomen, dus markeringsmarkup (al die gekleurde <span>-elementen) verdwijnt zonder de code aan te raken. Bevat de code zelf een reeks van drie backticks, dan wordt de omheining langer gemaakt dan die reeks, omdat de specificatie eist dat de sluitende omheining minstens zo lang is als de openende; zo blijft Markdown-documentatie over Markdown intact.

De opties uitgelegd

ATX- of setext-koppen

ATX-koppen (# Titel) werken voor alle zes niveaus en zijn wat vrijwel elke tool verwacht. Setext-koppen onderstrepen de tekst met === of ---; sommige stijlgidsen geven er voor H1 en H2 de voorkeur aan, maar ze kunnen H3 en lager niet uitdrukken.

Inline links of verwijzingslinks

Inline links houden elke URL naast zijn tekst, wat past bij korte documenten en AI-prompts. Verwijzingslinks verplaatsen URL’s naar een genummerde lijst onderaan, waardoor lange alinea’s leesbaar blijven in een platte-tekstverwerker en wat gebruikelijk is in documentatierepository’s.

Markdown-tekens escapen

Tekst als 2024. Een goed jaar of bestand_naam_hier zou verkeerd worden gelezen als lijst of als cursief, dus de converter escapet die tekens met backslashes. Dat klopt voor alles wat wordt weergegeven. Gaat de uitvoer naar een chat met een AI-model, een zoekindex of een platte notitie, haal dan het vinkje bij escapen weg voor schonere tekst.

Basis-URL

Relatieve URL’s hebben alleen zin op de pagina waar ze vandaan komen. Met een basis-URL wordt ../images/chart.png op https://voorbeeld.nl/blog/bericht https://voorbeeld.nl/images/chart.png, opgelost met dezelfde regels die browsers gebruiken.

Een hele webpagina omzetten

Deze converter haalt geen URL’s op. Een pagina in je browser kan de HTML van een andere site niet lezen tenzij die site het toestaat, en veel moderne pagina’s bouwen hun inhoud met JavaScript op na het laden, dus een ophaalactie aan de serverkant zou vaak een lege huls opleveren. Kopiëren van de weergegeven pagina voorkomt beide problemen: selecteer het artikel, kopieer, plak hier. Je krijgt de tekst die je echt ziet, met links en opmaak, en zonder de navigatie, cookiebanners of advertenties die je niet hebt geselecteerd. Wil je juist elke link uit een pagina halen, gebruik dan de link-extractor (Engels).

Veelvoorkomende problemen en oplossingen

• Een tabel verschijnt als HTML in de uitvoer. GFM staat uit, of kopbevordering staat uit en de tabel heeft geen koprij. Zet een van beide opties weer aan.
• Links wijzen naar de verkeerde plek. Ze waren relatief. Voeg het paginaadres toe als basis-URL.
• Regeleinden zien er raar uit. Een <br> wordt twee spaties aan het eind en een nieuwe regel, het harde regeleinde van CommonMark. Sommige editors knippen afsluitende spaties weg bij het opslaan, waardoor het weer een zacht regeleinde wordt.
• Er ontbreekt tekst. Komt de HTML uit Bron weergeven op een site vol JavaScript, dan staat de inhoud mogelijk helemaal niet in de markup. Kopieer dan van de weergegeven pagina.
• Alles is één alinea. De bron gebruikte <div>-elementen in plaats van <p> voor alinea’s. Markdown kent alleen de semantische elementen, dus een pagina van opgemaakte divs wordt platte lappen tekst.

Waarom HTML überhaupt naar Markdown omzetten?

Markdown houdt vast wat betekenis draagt (koppen, nadruk, links, lijsten, tabellen, citaten en code) en laat opmaakmarkup en inline stijlen vallen. Dat maakt het makkelijker te bewerken, te beoordelen in versiebeheer, te verplaatsen naar een kennisbank als Obsidian of een documentatiesite, of aan een AI-model te geven zonder zijn context aan class-attributen te besteden. Ontwikkelaars gebruiken het om cms-inhoud naar een statische site te verhuizen, schrijvers om concepten tussen editors te verplaatsen, onderzoekers om schone kopieën van bronnen te bewaren. Verzamel je bronnen in plaats van ze om te zetten, dan kan Marqly onderzoekslinks ordenen in één doorzoekbare bibliotheek, en de pagina voor ontwikkelaars laat zien hoe opgeslagen documentatie en codefragmenten vindbaar blijven.

Privé door ontwerp

De converter is de open source-bibliotheek Turndown met de plug-in voor GitHub-flavored Markdown, plus de eigen afhandeling van tabellen, code en links van deze pagina, allemaal meegebundeld. Ze werkt offline zodra ze is geladen, en je geplakte tekst, bestanden en instellingen blijven op je apparaat. Voor een snelle omvangcontrole voor of na de conversie telt de leestijdcalculator woorden en tekens ook lokaal.