Wat een Markdown-verwijderaar weggooit, en hoe je het houdt

“Haal de Markdown eruit” klinkt als één handeling. Het is in werkelijkheid een reeks kleine beslissingen, en een omzetter neemt ze allemaal voor je, of hij dat toegeeft of niet.

Dit is wat er meestal slecht wordt beslist.

De lijstnummering

De meest ingrijpende. De gangbare bibliotheken behandelen een lijst als een opmaakconstructie en slaan hem plat, waardoor 1. 2. 3. samen met de opsommingstekens verdwijnt.

Voor een lijst met bolletjes valt daar iets voor te zeggen. Voor een genummerde vernietigt het de betekenis: de nummers verwezen naar iets. Antwoorden op een genummerde vragenlijst, stappen in een reeks, gerangschikte punten — alles wordt een ongeordende hoop.

Nummering blijft hier bewaard, ook lijsten die bij 7 beginnen, en ook een genummerde lijst die in een andere genest is.

De URL achter een link

[de documentatie](https://example.com/gids) bevat twee stukjes informatie. Platte tekst heeft nergens om het tweede te laten, dus een omzetter moet het of uitschrijven of laten vallen.

Het laten vallen gaat stil en gebeurt vaak. De lezer krijgt “de documentatie” en geen manier om er te komen. De standaard schrijft hier beide — de documentatie (https://example.com/gids) — want een lezer die de link niet kan volgen is iets kwijt. Alleen tekst en alleen URL zijn beschikbaar wanneer je weet dat de link niet uitmaakt.

De taal van een codeblok

Een blok gemarkeerd met ```java draagt een feit: dit is Java. Haal de markering weg en dat feit gaat mee, en wat overblijft is een blok onverklaarde symbolen dat alles kan zijn.

De taal wordt als label meegegeven — [java] — zodat een lezer het kan zien. Uit, of behouden als de oorspronkelijke markering, als je dat liever hebt.

De alt-tekst van een afbeelding

Een afbeelding kan niet als afbeelding overleven. Maar de alt-tekst is een zin die iemand schreef om hem te beschrijven, en vaak is dat de enige beschrijving van die inhoud in het document. De afbeelding weggooien en de beschrijving houden is meestal beter dan beide weggooien.

Voetnoten, citaten, scheidingslijnen, frontmatter

Elk daarvan is inhoud die een verwijderaar stilletjes kan weghalen. Elk blijft hier standaard bewaard en is afzonderlijk uit te zetten.

Waarom verliesvrij de juiste standaard is

De toets die de meeste van deze gevallen beslecht: zou een lezer die de invoer nooit heeft gezien alles kunnen begrijpen wat erin stond, alleen uit de uitvoer?

Is het antwoord nee, dan heeft de omzetter namens de lezer informatie weggegooid zonder het te vragen. Een omzetter die iets laat staan dat je zelf moet verwijderen is tien seconden irritant. Een die iets verwijdert dat je nodig had, is een probleem dat je misschien pas merkt als het erop aankomt.

Dus de standaarden houden alles, en elke verwijdering is een schakelaar die jij kiest. Eén voorinstelling — Rapport en tabellen — breekt die regel bewust en haalt codeblokken en afbeeldingen weg, omdat hij bestaat om een vergelijkingstabel in een rapport te tillen waar een verdwaald fragment ruis is. Het is de uitzondering, hij zegt dat ook, en de voorinstelling Standaard haalt helemaal niets weg.

De dingen waarop echt geen antwoord bestaat

Sommige beslissingen hebben geen juiste standaard, alleen een context:

• Hoe ziet een kop eruit als niets hem kop kan maken? Vlak, hoofdletters, of # behouden.
• Hoe ziet een tabel eruit zonder tabel? Uitgelijnde kolommen, tabs, of label en waarde.
• Hoe ziet een takenlijst eruit? [ ], ☐, of niets.

Daarvoor bestaan de voorinstellingen. In plaats van er één te kiezen en universeel te noemen, beantwoordt elke voorinstelling al die vragen voor één bepaalde bestemming — een e-mailprogramma, een spreadsheet, een chatvenster, een documentatiepagina, een webformulier — en laat je een voorbeeld zien, zodat je de antwoorden ziet voordat je erop vertrouwt.