Markdown

vanlig text med några tecken som betyder formatering

Vad det är

Markdown är ett sätt att skriva ett dokument som en vanlig textfil, där några få inskrivna konventioner talar om för en konverterare vilken HTML den ska ta fram. Asterisker runt ett ord ger betoning, en brädgård före en rad gör den till rubrik, ett bindestreck inleder varje punkt i en lista, och hakparenteser följda av vanliga parenteser blir en länk. Namnet står både för syntaxen och för programmet den först levererades som. Filerna slutar oftast på .md eller .markdown, och dialekterna som vuxit fram ur den, bl.a. CommonMark och GitHub Flavored Markdown (GFM), går alla tillbaka på den.

John Gruber tog fram Markdown 2004 i samarbete med Aaron Swartz och skrev den första konverteraren i Perl. Den sista versionen, Markdown 1.0.1, är daterad den 17 december 2004. Hans uttalade mål var läsbarhet framför allt: ett Markdown-dokument ska kunna publiceras som det är, som ren text, utan att se ut som om det märkts upp med taggar eller formateringsinstruktioner. Den enskilt största förebilden för syntaxen var, skrev han, hur folk redan formaterade e-post i ren text. Det som syntaxen inte täcker skrivs som HTML mitt i texten, utan någon växel eller avgränsare, eftersom Markdown i hans synsätt är ett skrivformat och HTML ett publiceringsformat.

Några rader visar det mesta:

Flytten tog **en kväll**, i tre steg:

- stoppa skrivningarna
- kopiera data med `pg_dump`
- peka [applikationen](https://example.com/app/) mot den nya värden

En konverterare gör om det till ett stycke med ett strong-element, en lista med tre punkter, ett kodfragment och en länk, och källtexten läses fortfarande som en anteckning som någon har skrivit.

Varför det spelar roll

Källan är dokumentet, och ren text överlever alla verktyg runt omkring den. En Markdown-fil öppnas i vilken editor som helst, jämförs rad för rad i versionshanteringen och går lätt att granska i en pull request. Formatet hör inte till en leverantör som kan lägga ned det, och att flytta en mängd text från ett system till ett annat handlar om att kopiera filer.

Priset är tvetydighet. CommonMark-projektet säger det rakt ut: beskrivningen från Gruber anger inte syntaxen entydigt, och hans skript hade buggar och uppdaterades senast i december 2004. År 2014 fanns därför dussintals implementationer, och var och en fyllde luckorna på sitt eget sätt. Projektets exempel är ett dokument som visas på ett sätt i en wiki på GitHub och på ett annat när det konverteras till DocBook med Pandoc. Eftersom ingenting i Markdown räknas som ett syntaxfel märks en avvikelse först när någon tittar på resultatet. Projektet hänvisar till Babelmark 3, som kör samma indata genom fler än tjugo implementationer för att se om de är överens.

CommonMark, som startade 2014, svarar med en specifikation skriven av John MacFarlane som knyter varje regel till exempel på indata och den exakta HTML som ska komma ut. I version 0.31.2, daterad den 28 januari 2024, är exemplen 652 till antalet. GitHub definierar sin egen dialekt, GFM, som en strikt övermängd av CommonMark och lägger till tabeller, uppgiftslistor, genomstruken text, utökade autolänkar och ett filter som oskadliggör en kort lista med råa HTML-taggar. Konverteraren i Hugo, Goldmark, följer CommonMark-specifikationen och är kompatibel med GFM.

Markdown har också ett namn i trafiken mellan program. Sedan mars 2016 registrerar RFC 7763 mediatypen text/markdown för hela familjen av syntaxer, med en obligatorisk parameter charset och en valfri parameter variant som anger vilken dialekt en fil är skriven i.

Så ser det ut i praktiken

De handskrivna sidorna på den här webbplatsen är Markdown som läggs ut med mallar i Go, och sidan med medverkande verktyg räknar upp båda bland verktygen som sidorna görs med, bredvid Hugo, som är webbplatsens statiska webbplatsgenerator. Samma sida nämner markdownlint bland de linters som håller källtexten ärlig, i en kvalitetsgrind där varje anmärkning räknas som ett fel.

Sidan om att vara redo för AI-agenter vänder på formatet. Varje sida här har en Markdown-tvilling på samma adress, som nås genom att lägga till index.md eller genom att be om text/markdown, och bygget läser varje tvilling efter kvarlämnad markup och vägrar publicera när någon är fel. Tvillingen till den sidan finns en begäran bort:

curl -sL https://engineer.company/ai-ready/index.md

Runt 50 000 ord programvarudokumentation skrevs i Markdown i GitHub, Craft och Confluence, mycket av det för hand. Texterna täckte arkitekturen, processerna och det praktiska instruktionsmaterialet som folk frågade efter om och om igen. De hölls versionshanterade och lätta att hitta, och nya medarbetare kom in i arbetet snabbare.

Var det går fel

Fetstilen syns som asterisker. Läsaren ser två asterisker på var sida om ett ord som skulle ha varit fetstilt, och alla kontroller förblir gröna, eftersom HTML-koden är giltig och länkarna fungerar. CommonMark öppnar betoning bara vid en vänsterflankerande följd av asterisker, och en följd som efterföljs av skiljetecken, t.ex. hakparentesen i en länk, räknas bara när ett blanksteg eller ett skiljetecken står framför den. En bokstav framför gör asteriskerna bokstavliga, och det gör även allt som en mallmotor sätter dit innan Markdown tolkas: Hugo ersätter en shortcode med en platshållare av bokstäver och siffror. Mallen för webbplatsens Markdown-tvillingar noterar att när blanksteget mellan en shortcode och fetstilen bredvid togs bort, gick fetstilen sönder i 60 punkter på tre språk. Behåll blanksteget och kontrollera den renderade sidan i stället för källan. Webbplatsens grind har en kontroll som läser den byggda HTML-koden efter Markdown som nådde läsaren som skiljetecken.

Samma fil ser olika ut på två ställen. En nästlad lista plattas till i ett system och nästlas i ett annat, eller en brädgård i början av en rad blir en rubrik i en konverterare och förblir text i nästa, och ingenting rapporterar det, eftersom Markdown saknar syntaxfel att rapportera. Orsaken är en skillnad mellan dialekter: två konverterare som fyller en av de ursprungliga luckorna på olika sätt. Bestäm vilken dialekt ett projekt skrivs i, för det mesta CommonMark eller GFM, använd en linter som håller filerna till den, och kör tveksam indata genom mer än en implementation innan ni förlitar er på den.

Markdown-kopian av en sida bär med sig HTML. Den som läser textversionen möter råa svg-element, eller ett telefonnummer som börjar med en numerisk teckenreferens där plustecknet skulle stå. En komponent som renderar till HTML för webbsidan renderar samma HTML till alla andra format om den inte får besked om något annat. Hugo slår upp mallen för en shortcode per utdataformat och faller tillbaka på HTML-mallen. Webbplatsens shortcode-mallar dokumenterar båda fallen, 49 råa svg-element i Markdown-kopian av sidan med medverkande verktyg och kontaktsidans nummer escapat för HTML, och en shortcode som skriver någon form av markup har nu en egen mall för Markdown-utdata. Grinden kontrollerar dessutom att Markdown-tvillingarna varken bär rå HTML eller HTML-entiteter, med kod undantagen.

Rå HTML försvinner från sidan. Ett block HTML som skrivits in i Markdown-texten syns inte på den byggda sidan, fast källan ser bra ut. Syntaxen från Gruber låter HTML stå var som helst i texten, men en konverterare får vägra: inställningen unsafe för Goldmark i Hugo är avslagen som standard, så rå HTML blandad i Markdown renderas inte, och GFM escapar en kort lista med taggar som script och iframe så att de skrivs ut som text. Använd hellre det som generatorn erbjuder, en shortcode eller en render hook i Hugo, eller slå på inställningen medvetet och acceptera det den släpper igenom.

Lintern släpper igenom det den blivit tillsagd att strunta i. En Markdown-fil med trasig struktur går igenom granskningen eftersom markdownlint inte rapporterar något. Reglerna som skulle ha fångat felet var avslagna i konfigurationen, utan något nedskrivet skäl. Webbplatsens utvecklingsregler noterar att markdownlint en gång låg i en JSON-fil med sex regler avslagna och inga kommentarer, och att två av de sex visade sig dölja verkliga defekter när de mättes. Skriv skälet bredvid varje avslagen regel, i ett format som kan rymma en kommentar, så att nästa person kan säga emot.

Läs mer

Ordlista