{"canonical_url":"https://engineer.company/nb/glossary/markdown/","content_markdown":"# Markdown\n\n## Hva det er\n\nMarkdown er et dokumentformat i ren tekst. Stjerner rundt et ord gir uthevet tekst, `#`\nførst på en linje gir en overskrift, `-` starter et listepunkt, og en lenke skrives som\nklammer og parenteser: `[tekst](adresse)`. Navnet brukes både om selve syntaksen og om\ndet opprinnelige programmet som gjør teksten om til HTML. Filene får som regel endelsen\n`.md` eller `.markdown`, og dialektene som har vokst fram fra formatet, blant annet CommonMark\nog GitHub Flavored Markdown, forkortet GFM, går under samme navn.\n\nJohn Gruber utviklet formatet i 2004 sammen med Aaron Swartz og skrev konverteren i\nPerl. Den siste utgaven av den, 1.0.1, er datert 17. desember 2004. Designmålet var\nlesbarhet: et Markdown-dokument skal kunne publiseres som det står, som ren tekst, uten\nå se ut som om noen har strødd tagger og formateringskoder utover det. Gruber oppgir at\nden største inspirasjonen var måten folk allerede formaterte e-post i ren tekst på.\n\nMarkdown erstatter ikke HTML. Der syntaksen ikke rekker, skriver du HTML rett inn i\nteksten, uten noen egen markering rundt. Grubers begrunnelse er at Markdown er et format\nå skrive i, mens HTML er et format å publisere i, så det ene kan bo inni det andre.\n\nSlik ser en liten bit ut:\n\n```markdown\nThe move took **one evening**, in three steps:\n\n- stop the writes\n- copy the data with `pg_dump`\n- point the [application](https://example.com/app/) at the new host\n```\n\nKonverteren lager av dette et avsnitt med et `strong`-element, en liste med tre punkter,\net kodespenn og en lenke. Men teksten kan leses like godt før den er konvertert, og det\ner hele idéen.\n\n## Hvorfor det er viktig\n\nRen tekst lever lenger enn verktøyene rundt den. En Markdown-fil kan sammenlignes linje\nfor linje i versjonskontroll, gjennomgås i en pull request og åpnes i hvilken som helst\neditor, og ingen leverandør kan legge ned formatet under deg. Dokumentasjon som ligger i\nsamme repo som koden, blir dermed endret i samme arbeidsflyt som koden og gjennomgått av\nde samme folkene.\n\nPrisen er tvetydighet. CommonMark-prosjektet skriver rett ut at Grubers beskrivelse av\nsyntaksen ikke er entydig, og at referanseskriptet hadde feil og sist ble oppdatert i\ndesember 2004. Hver ny implementasjon måtte derfor fylle hullene på egen hånd, og i 2014\nfantes det dusinvis av dem. Spesifikasjonen viser et eksempel der ett og samme dokument\ngjengis på én måte i en GitHub-wiki og på en annen i Pandocs DocBook-utdata. Markdown\nkjenner ingen syntaksfeil, alt er gyldig input, så en forskjell viser seg først i\nresultatet. Verktøyet Babelmark 3 sender samme tekst gjennom mer enn 20\nimplementasjoner, slik at du ser hvor de spriker.\n\nSvaret på tvetydigheten kom i 2014, da CommonMark startet med en spesifikasjon skrevet\nav John MacFarlane. Den knytter hver regel til eksempler på input og den HTML-en som\nskal komme ut, og versjon 0.31.2, datert 28. januar 2024, har 652 slike eksempler.\nDermed kan en implementasjon testes, ikke bare beskrives.\n\nGFM er et strengt supersett av CommonMark. GitHub legger til tabeller, oppgavelister\n(task list items), gjennomstreking, utvidede autolenker og et filter som uskadeliggjør\nen kort liste med rå HTML-tagger, og hver utvidelse er merket i spesifikasjonen. Hugo,\nden statiske nettstedsgeneratoren, bruker Goldmark, som følger CommonMark og er\nkompatibel med GFM.\n\nFormatet har også sin egen medietype. RFC 7763 fra mars 2016 registrerer\n`text/markdown`, med en obligatorisk `charset`-parameter og en valgfri `variant` som kan\nsi hvilken dialekt teksten er skrevet i.\n\n## Slik ser det ut i praksis\n\nDe håndskrevne sidene på dette nettstedet er skrevet i Markdown og lagt ut med Go-maler,\nog [kolofonen](/nb/credits/) nevner begge blant verktøyene sidene er laget med, ved\nsiden av Hugo. Den samme siden nevner markdownlint blant linterne som holder kildekoden\nærlig, i en kvalitetsport der hver eneste melding regnes som en feil.\n\n[Siden om å være klar for AI-agenter](/nb/ai-ready/) snur formatet rundt. Hver side her\nhar en Markdown-tvilling på samme adresse: legg til `index.md`, eller be om\n`text/markdown`. Bygget går gjennom hver tvilling på jakt etter rester av markup og\nnekter å publisere når én av dem er feil. Tvillingen til den engelske utgaven av siden\ner én forespørsel unna:\n\n```sh\ncurl -sL https://engineer.company/ai-ready/index.md\n```\n\nDen norske tvillingen ligger på samme sti med `/nb` foran.\n\nI rollen som produkteier og prosjektutviklingsleder ble\n[rundt 50 000 ord programvaredokumentasjon](/nb/portfolio/wrote-50000-words-of-software-documentation/)\nskrevet i Markdown, fordelt på GitHub, Craft og Confluence etter hvor hver del hørte\nhjemme, og mye av det for hånd. Dokumentasjonen dekket arkitekturen, prosessene og det\npraktiske veiledningsstoffet folk stadig spurte om. Den lå under versjonskontroll, var\nlett å finne, og nye folk kom raskere i gang.\n\n## Hvor det går galt\n\n**Fet skrift kommer ut som stjerner.** Leseren ser to stjerner på hver side av et ord\nsom skulle vært fett, og alle kontroller er grønne, fordi HTML-en er gyldig og lenkene\nvirker. CommonMark åpner uthevet tekst bare på en venstreflankerende stjernerekke, og\nstår rekken foran et skilletegn, f.eks. klammen i en lenke, teller den bare når det står\nmellomrom eller et annet skilletegn foran den. En bokstav foran gjør stjernene til\nvanlige tegn, og det gjør også alt en malmotor setter inn før Markdown-teksten tolkes:\nHugo bytter ut en shortcode med en plassholder av bokstaver og sifre. Malen for\nMarkdown-tvillingene på dette nettstedet har en merknad om at mellomrommet mellom en\nshortcode og den fete teksten ved siden av en gang ble fjernet, og at fet skrift da\nsluttet å virke i 60 listepunkter fordelt på tre språk. Behold mellomrommet, og sjekk\nden ferdige siden og ikke kilden. Kvalitetsporten her har en kontroll som leser den\nbygde HTML-en etter Markdown som nådde leseren som tegnsetting.\n\n**Den samme filen gjengis på to måter.** En nøstet liste blir flat i ett system og\nnøstet i et annet, eller en `#` først på en linje blir en overskrift i én konverter og\nblir stående som tekst i den neste. Ingenting melder fra, fordi Markdown ikke har\nsyntaksfeil å melde. Årsaken er en forskjell i dialekt: to konvertere som fyller et av\nde opprinnelige hullene hver på sin måte. Bestem hvilken dialekt prosjektet skrives i,\nsom oftest CommonMark eller GFM, bruk en linter som holder filene til den, og kjør\ntvilsom input gjennom mer enn én implementasjon før du stoler på den.\n\n**Markdown-kopien av en side bærer med seg HTML.** Den som leser ren tekst-utgaven,\nmøter rå `svg`-elementer, eller et telefonnummer som begynner med en numerisk\ntegnreferanse der plusstegnet skulle stått. En komponent som lager HTML til nettsiden,\nlager den samme HTML-en i alle andre formater også, med mindre noen sier noe annet. Hugo\nslår opp malen til en shortcode for hvert utdataformat og faller tilbake på HTML-malen.\nShortcode-malene på dette nettstedet har merknader om begge tilfellene: 49 rå\n`svg`-elementer i Markdown-kopien av kolofonen, og telefonnummeret på kontaktsiden\nescapet for HTML. En shortcode som skriver markup av noe slag, får nå sin egen mal for\nMarkdown-utdataene, og kvalitetsporten sjekker at tvillingene verken har rå HTML eller\nHTML-entiteter, med kode unntatt.\n\n**Rå HTML forsvinner fra siden.** En HTML-blokk skrevet inn i Markdown-teksten mangler\npå den bygde siden, mens kilden ser riktig ut. Grubers syntaks lar HTML stå hvor som\nhelst i teksten, men en konverter står fritt til å avvise den. I Hugo er\nGoldmark-innstillingen `unsafe` slått av som standard, så rå HTML blandet inn i Markdown\nblir ikke gjengitt, og GFM escaper en kort liste med tagger som `script` og `iframe`,\nslik at de skrives ut som tekst. Bruk det generatoren tilbyr i stedet, i Hugo en\nshortcode eller en [render hook](https://gohugo.io/render-hooks/), eller slå\ninnstillingen på med vilje og godta det den slipper gjennom.\n\n**Linteren slipper gjennom det den er bedt om å overse.** En Markdown-fil med ødelagt\nstruktur kommer gjennom gjennomgangen fordi markdownlint ikke rapporterer noe. Reglene\nsom ville fanget feilen, var slått av i konfigurasjonen, uten at noen hadde skrevet ned\nhvorfor. Utviklingsreglene for dette nettstedet forteller at markdownlint en gang lå i\nen JSON-fil med seks regler slått av og ingen kommentarer, og at to av de seks skjulte\nekte feil da de ble målt. Skriv begrunnelsen ved siden av hver regel som er slått av, i\net format som har plass til kommentarer, så den neste kan være uenig.\n\n## Les mer\n\n- [CommonMark Spec](https://spec.commonmark.org/) — spesifikasjonen regel for regel,\n  hver knyttet til eksempler på input og HTML-en den skal gi.\n- [CommonMark](https://commonmark.org/) — hvorfor en spesifikasjon trengtes, hvordan\n  implementasjonene gled fra hverandre, og hvem som vedlikeholder den.\n- [Markdown, by John Gruber](https://daringfireball.net/projects/markdown/) — den\n  opprinnelige beskrivelsen, designmålet og Perl-skriptet.\n- [Markdown: Syntax](https://daringfireball.net/projects/markdown/syntax) — Grubers egen\n  gjennomgang av syntaksen, med regelen for HTML i teksten.\n- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) — GitHubs dialekt som\n  et supersett av CommonMark, med hver utvidelse merket.\n- [RFC 7763: The text/markdown Media Type](https://www.rfc-editor.org/rfc/rfc7763) —\n  medietypen, den obligatoriske `charset` og parameteren `variant`.\n\n\u003chttps://engineer.company/nb/glossary/markdown/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Markdown for deg som skriver dokumentasjon i ren tekst: hvor formatet kom fra, CommonMark mot GFM og feilene som gir stjerner der det skulle stått fet skrift.","formats":{"gemtext":"https://engineer.company/nb/glossary/markdown/index.gmi","gopher":"https://engineer.company/nb/glossary/markdown/gophermap","html":"https://engineer.company/nb/glossary/markdown/","json":"https://engineer.company/nb/glossary/markdown/index.json","markdown":"https://engineer.company/nb/glossary/markdown/index.md","pdf":"https://engineer.company/nb/glossary/markdown/index.pdf"},"kind":"page","language":"nb","title":"Hva er Markdown?","url":"https://engineer.company/nb/glossary/markdown/","version":1}