Voor wie

Documentatie naar Markdown zonder opruimen

Documentatie migreren betekent meestal: HTML omzetten en daarna langer bezig zijn met weghalen wat de omzetter heeft bewaard. Dat weghalen is waar Clean Clipper om heen is gebouwd, en het is ook het deel dat gemeten is: nul achtergebleven HTML-tags over 512 pagina’s, en taallabels die op de code-fences blijven staan.

Waarom een migratie uitloopt

De omzetting zelf is het probleem niet: kopjes worden kopjes en lijsten worden lijsten. Het probleem is wat er meekomt. De navigatieboom in het zijmenu, de versiekiezer, de balk met “feedback geven” en de inhoudsopgave rechts staan in dezelfde container als de tekst, dus ze belanden in elk bestand. Bij dertig pagina’s is dat dertig keer hetzelfde handwerk.

Daarnaast verliest de inhoud juist wat haar technisch maakt. Code-fences komen kaal binnen, parametertabellen breken op de cel waarin een voorbeeld staat, en losse div- en span-resten blijven midden in de tekst staan. Wie dat achteraf met zoek-en-vervang opruimt, sloopt vroeg of laat iets wat wel inhoud was.

En een migratie gebeurt nooit één keer. Er is een proefronde op tien pagina’s, daarna het echte werk, en daarna nog een ronde omdat de bron intussen is bijgewerkt. Dat werkt alleen als dezelfde pagina twee keer hetzelfde bestand oplevert: dan is de tweede ronde een diff en zie je in één oogopslag wat er inhoudelijk veranderd is. Levert je omzetter elke keer iets anders op, dan is elke ronde weer volledig handwerk.

Wat er overkomt

• Kopjes, lijsten, tabellen, code-fences en voetnoten worden allemaal standaard Markdown
• Taallabels blijven op de code-fences staan – 73 van de 156 op het technische corpus, tegen 20 en 0
• Nul achtergebleven HTML-tags over 512 gemeten pagina’s
• Navigatiebalken, versiekiezers en “op deze pagina”-blokken worden weggeknipt, niet omgezet
• Lege kopjes, een veelvoorkomend restant van navigatieblokken, vervallen
• Sjabloon voor de bestandsnaam en een submap houden een geïmporteerde set geordend
• Dezelfde pagina levert bij een tweede ronde hetzelfde bestand op, dus die ronde is een diff en geen herhaling van het handwerk
• Het veld extraction noteert per bestand welke weg is gebruikt – dom of jsonld-articlebody – zodat afwijkende pagina’s opvallen

## 3.2 Paginering

Een collectie wordt gepagineerd teruggegeven. De cliënt volgt de link met
relatie `next` tot die ontbreekt.

| Parameter | Type | Verplicht |
| --- | --- | --- |
| `limit` | integer | nee |
| `cursor` | string | nee |

### 3.2.1 Foutsituaties

Een set documentatie overzetten

De volgorde is hier belangrijker dan de instellingen: eerst tien pagina’s als proef, dan pas de rest. Wat je in de proefronde ontdekt, verandert meestal de bestandsnaam.

1. Open Opties met een rechtermuisklik op het icoon en zet de bestemming op de map waarin de nieuwe documentatie komt te staan – bij voorkeur meteen de repository, zodat elke ronde in versiebeheer zichtbaar is.
2. Zet het sjabloon voor de bestandsnaam op {domain}-{title}. Bij documentatie van meerdere producten of versies botsen de titels; het domein ervoor houdt ze uit elkaar zonder dat je iets hoeft te bedenken.
3. Laat source en extraction in de frontmatter aan staan en zet author uit. source is waar de pagina vandaan kwam en dus waar je bij een tweede ronde opnieuw moet zijn; extraction laat zien welke pagina’s afwijkend zijn binnengekomen.
4. Zet wat een klik op het icoon doet op “opslaan in map” en controleer Alt+Shift+M. Bij dertig pagina’s achter elkaar is elke handeling die je overhoudt er dertig.
5. Doe eerst tien pagina’s als proef en bekijk ze in een editor. Let op drie dingen: de kopniveaus, de tabellen met een voorbeeld in een cel, en of tabbladen open stonden. Wat je hier vindt, geldt voor de hele set.
6. Loop daarna de resterende pagina’s langs. Klap onderweg tabs en accordeons open voordat je ophaalt – dat is de enige stap die je met geen enkele instelling kunt automatiseren.
7. Haal bij een tweede ronde dezelfde pagina’s opnieuw op in een aparte map en vergelijk de twee mappen met een diff. Wat verschilt, is wat de bron heeft gewijzigd.

Instellingen voor een migratie

Deze waarden gaan uit van een set die in versiebeheer terechtkomt en die je meer dan één keer zult ophalen.

## Installeren

> **Let op:** twee hoofdversies tegelijk overslaan wordt niet ondersteund.

npm

```bash
npm install voorbeeld-cli --save-dev
```

pnpm

```bash
pnpm add -D voorbeeld-cli
```

Beide tabbladen stonden in de DOM en verborgen met CSS, dus beide komen mee.
Een tabblad dat pas bij een klik wordt geladen, had hier ontbroken.

Drie stappen in een migratie

De proefronde die de bestandsnaam bepaalt

Je haalt tien pagina’s op met {title} als naam en ziet dat drie ervan “Aan de slag” heten, want ze horen bij drie verschillende producten. Je zet het sjabloon om naar {domain}-{title} en haalt die tien opnieuw op.

Dat is precies waarom een proefronde eerst gaat. Bij dertig bestanden is hernoemen nog te doen; bij driehonderd, met interne verwijzingen die al naar die namen wijzen, is het een aparte klus geworden.

Een installatiehandleiding met tabbladen

De pagina toont de installatiestappen in tabbladen voor npm en pnpm, en daarboven een waarschuwingsblok. Beide tabbladen staan in de DOM en zijn met CSS verborgen, dus ze komen allebei mee, achter elkaar, met hun code-fences en taallabels. Het waarschuwingsblok wordt een blockquote.

Bij een site die het tweede tabblad pas na een klik inlaadt, gaat dat niet vanzelf: dan haal je de pagina twee keer op, één keer per tabblad, of je klapt eerst alles open. Dat is de enige stap in de hele migratie die je met de hand moet doen.

De tweede ronde als diff

Twee maanden na de eerste import is de brondocumentatie bijgewerkt. Je haalt dezelfde pagina’s opnieuw op, in een aparte map, met precies dezelfde instellingen. Dezelfde pagina levert hetzelfde bestand op, dus een diff tussen de twee mappen toont alleen wat de bron heeft veranderd.

Wat je dan overhoudt, is een lijst inhoudelijke wijzigingen in plaats van een lijst opmaakverschillen. Dat is het verschil tussen een tweede ronde van een uur en een tweede ronde van een week.

Tegenover de gebruikelijke manieren

Documentatie naar Markdown krijgen kan op vijf manieren, en ze worden alle vijf gebruikt. Dit is wat ze opleveren en wat ze kosten.

Als de omzetting tegenvalt

De helft van een tabblad ontbreekt

Sites doen dit op twee manieren. Rendert de site alle tabbladen en verbergt ze met CSS, dan komen ze allemaal mee, achter elkaar. Laadt de site een tabblad pas in na een klik, dan staat het tot dat moment niet in de DOM en komt het niet mee. Klap alles open voordat je ophaalt, of haal per tabblad een clip op.

Mijn admonitions zijn blockquotes geworden

Markdown kent geen standaardsyntaxis voor waarschuwingen, notities en tips, dus wordt de inhoud een blockquote met de kop vet erin. De tekst blijft dus volledig behouden en de vorm niet. Gebruikt je doelsysteem een eigen syntaxis voor callouts, dan is dat een zoek-en-vervang over de blockquotes – één patroon, over de hele set.

Kruisverwijzingen wijzen nog naar de oude site

Dat klopt en dat is met opzet: links blijven staan als links naar de oorspronkelijke pagina en worden niet omgeschreven naar je nieuwe bestandsstructuur. Die structuur kent de extensie niet, en gokken zou stille kapotte links opleveren. Het omschrijven doe je bij de import, en dan zie je meteen welke doelen nog niet bestaan.

Er staat jsonld-articlebody bij een paar pagina’s

Die pagina’s hadden hun tekst niet uitgerenderd maar wel in gestructureerde data staan, en daar is toen uit gelezen. In een migratie is dat een signaal om juist die bestanden na te kijken: de versie in de gestructureerde data is soms korter dan wat op het scherm stond, en soms juist vollediger.

Wat het niet doet

Er zit geen crawler en geen batchverwerking in: je haalt de pagina’s op die je zelf bezoekt, één tegelijk. Admonitions en callouts worden blockquotes, want Markdown kent er geen standaardsyntaxis voor. Tabs, accordeons en andere onderdelen die pas na een klik inhoud tonen, komen alleen mee als ze op dat moment open staan. En afbeeldingen en diagrammen blijven links naar de oorspronkelijke site.

Vragen