Markdown

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:

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

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

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:

```sh
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

  * CommonMark Spec — specifikationen regel för regel, var och en
knuten till exempel på indata och den HTML som ska komma ut.

  * CommonMark — varför en specifikation behövdes, hur
implementationerna gled isär och vem som underhåller den.

  * Markdown, by John Gruber — originalbeskrivningen, designmålet
och skriptet i Perl.

  * Markdown: Syntax — Grubers egen genomgång av syntaxen, inklusive
regeln för HTML i löptext.

  * GitHub Flavored Markdown Spec — dialekten från GitHub som en
övermängd av CommonMark, med varje tillägg utmärkt.

  * RFC 7763: The text/markdown Media Type — mediatypen, den
obligatoriska parametern `charset` och parametern `variant`.

hDen här sidan på webben	URL:https://engineer.company/sv/glossary/markdown/	engineer.company	70
