Markdown för PDF: hur man delar dokumentation utan att ta förvaret med sig

README, installationsinstruktioner, projektanteckningar: Mycket dokumentation skapas i Markdown eftersom det är lätt att skriva och versionera. Men inte alla mottagare vill öppna en kodredigerare. Att exportera en PDF kan göra det lättare att skicka, så länge innehållet inte är beroende av funktioner som omvandlaren inte tolkar.

Testa med ett representativt utdrag

Innan du konverterar femtio sidor, välj ett exempel med en titel, numrerad lista, kodblock och länk. DEMarkdown för PDFkänner igen grundläggande strukturer, men presentationen av komplexa tabeller, externa bilder och kodavsnitt matchar inte nödvändigtvis den för en fullständig Markdown-renderare.

Detta beror på att Markdown har variationer. Vissa tillägg accepterar tabeller, diagram och fotnoter, medan andra bara tolkar titlar, listor och enkel formatering. Filen.mdgaranterar inte ensam att mottagaren kommer att se samma sida i alla program.

Skriv för dem som inte kommer att se förvaret

En relativ länk som../images/flux.pngDet kan fungera inom projektet och gå vilse utanför det. Om bilden är viktig, inkludera en beskrivning eller exportera den med en redigerare som förstår lokala filer. Länkar till extern dokumentation förtjänar också granskning, eftersom en trasig URL blir en värdelös referens.

Installationslistor måste visa kommandon i rätt ordning. Kontrollera att blocken är tydligt åtskilda och att tecken som snedstreck, bindestreck och citattecken förblir läsbara. I manualer kan en liten skillnad i kommandot hindra någon från att återskapa proceduren.

Välj format efter målgrupp

För att samarbeta med dokumentation, behåll Markdown som din primära källa. För att distribuera en läsversion är PDF bekvämt. Om du behöver sökningar, tillgängliga länkar och kopierbar kod, använd en högfientlig textexport i lämplig redigerare.

Jämför i slutet den genererade filen med Markdown-förhandsgranskningen. Läs det som någon som aldrig har öppnat projektet: kan de förstå stegen bara utifrån det som finns i PDF-filen? Om så var fallet fyllde omvandlingen sin roll.

Dokumentationen måste överleva utanför redaktören

Markdown är utmärkt för att skriva guider och tekniska anteckningar eftersom titlar, listor och exempel är synliga även i vanlig text. Utmaningen uppstår när PDF:en behöver representera kodblock, tabeller eller stora bilder. En rad som är för lång kan sträcka sig utanför marginalen och en bred tabell kan kräva en annan sidorientering. Gör därför en testexport innan du distribuerar en hel manual.

När det finns länkar till lokala filer, kontrollera att mottagaren kommer att kunna komma åt dem; en sökväg som fungerar på din dator kanske inte betyder något på en annan dator. I bilder, föredra en bildtext som förklarar vad som visas istället för bara "Figur 1". Om dokumentet uppdateras ofta, spara Markdown-filen som huvudkälla och generera versionerade PDF-filer för varje publikation.