{"canonical_url":"https://engineer.company/glossary/markdown/","content_markdown":"# Markdown\n\n## What it is\n\nMarkdown is a way of writing a document as an ordinary text file in which a\nhandful of typed conventions, such as asterisks around a word for emphasis, a\nhash in front of a heading, a hyphen in front of each list item and square\nbrackets followed by parentheses for a link, tell a converter which HTML to\nproduce. The name covers both the syntax and the program it first shipped as,\nfiles usually end in `.md` or `.markdown`, and the dialects that grew from it,\nCommonMark and GitHub Flavored Markdown (GFM) among them, all answer to it.\n\nJohn Gruber developed it in 2004 in collaboration with Aaron Swartz, and wrote\nthe first converter in Perl; its last release, Markdown 1.0.1, is dated 17\nDecember 2004. His stated goal was readability above all: a Markdown document\nshould be publishable as it is, as plain text, and should not look as though\ntags or formatting instructions had been used to mark it up. The biggest single\ninfluence on the syntax, he wrote, was the way people already formatted\nplain-text email. Anything the syntax does not cover is written as HTML in the\nmiddle of the text, with no switch or delimiter, because in his framing Markdown\nis a writing format and HTML is the publishing format.\n\nA few lines show most of it:\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\nA converter turns that into a paragraph with a `strong` element, a list of three\nitems, a code span and a link, and the source still reads as a note somebody\ntyped.\n\n## Why it matters\n\nThe source is the document, and plain text outlives every tool around it. A\nMarkdown file opens in any editor, compares line by line in version control and\nreviews cleanly in a pull request. No vendor can retire the format, and moving a\nbody of writing from one system to another is a matter of copying files.\n\nThe price is ambiguity. The CommonMark project puts it plainly: Gruber's\ndescription does not specify the syntax unambiguously, and his script had bugs\nand was last updated in December 2004, so by 2014 there were dozens of\nimplementations, each filling the gaps its own way. Its example is a document\nthat renders one way on a GitHub wiki and another way when converted to DocBook\nwith Pandoc. And because Markdown rejects no input as a syntax error, a\ndivergence surfaces only when somebody looks at the output. The project points\nto Babelmark 3, which runs the same input through more than twenty\nimplementations to see whether they agree.\n\nCommonMark, started in 2014, answers with a specification written by John\nMacFarlane that pins each rule to examples of input and the exact HTML it must\nproduce: 652 of them in version 0.31.2, dated 28 January 2024. GitHub defines\nits own dialect, GFM, as a strict superset of CommonMark, adding tables, task\nlist items, strikethrough, extended autolinks and a filter that disarms a short\nlist of raw HTML tags. Hugo's Markdown converter, Goldmark, conforms to the\nCommonMark specification and is compatible with GFM.\n\nMarkdown also has a name on the wire. Since March 2016, RFC 7763 registers\n`text/markdown` for the whole family of syntaxes, with a required `charset` and\nan optional `variant` parameter that says which dialect a file is written in.\n\n## What it looks like in practice\n\nThe hand-written pages of this site are Markdown, laid out by Go templates, and\n[the credits page lists both](/credits/) among the tools the pages are made\nwith, beside Hugo, the static site generator. The same page names markdownlint\namong the linters that keep the source honest, in a quality gate where every\ndiagnostic is an error.\n\n[The page on making a site readable to AI agents](/ai-ready/) turns the\nformat round: every page here has a Markdown twin at the same address, reached\nby adding `index.md` or by asking for `text/markdown`, and the build reads\nevery twin for leftover markup and refuses to publish when one is wrong. The\ntwin of that page is one request away:\n\n```sh\ncurl -sL https://engineer.company/ai-ready/index.md\n```\n\n[Around 50,000 words of software documentation](/portfolio/wrote-50000-words-of-software-documentation/)\nwent into Markdown across GitHub, Craft and Confluence, much of it written by\nhand. It covered the architecture, the processes and the how-to material people\nkept asking about, was kept version-controlled and findable, and got new people\nup to speed faster.\n\n## Where it goes wrong\n\n**Bold prints as asterisks.** A reader sees two asterisks on either side of a\nword that was meant to be bold, and every check stays green, because the HTML is\nvalid and the links still work. CommonMark opens emphasis only on a\nleft-flanking run of asterisks, and a run followed by punctuation, such as the\nbracket of a link, counts only when whitespace or punctuation stands in front of\nit. A letter in front keeps the asterisks literal, and so does anything a\ntemplate engine puts there before the Markdown is parsed: Hugo replaces a\nshortcode with a placeholder made of letters and digits. This site's Markdown\ntwin template records that removing the space between a shortcode and the bold\nbeside it broke the bold on 60 bullets across three languages. Keep the space,\nand check the rendered page rather than the source; this site's gate has a check\nthat reads the built HTML for Markdown that reached a reader as punctuation.\n\n**The same file renders two ways.** A nested list flattens on one system and\nnests on another, or a hash at the start of a line makes a heading in one\nconverter and stays text in the next, and nothing reports it, because Markdown\nhas no syntax errors to report. The cause is a dialect difference: two\nconverters filling one of the original gaps in different ways. Name the dialect\na project is written in, CommonMark or GFM in most cases, use a linter that\nholds files to it, and run doubtful input through more than one implementation\nbefore relying on it.\n\n**The Markdown copy of a page carries HTML.** A reader of the plain-text version\nmeets raw `svg` elements, or a phone number that opens with a numeric character\nreference where the plus sign should be. A component that renders to HTML for\nthe web page renders the same HTML into every other format unless it is told\notherwise; Hugo looks up a shortcode's template per output format and falls back\nto the HTML one. This site's shortcode templates record both cases, 49 raw `svg`\nelements in the Markdown copy of the credits page and the contact page's number\nescaped for HTML, and a shortcode that writes any markup now gets its own\ntemplate for the Markdown output. The gate also checks that the Markdown twins\ncarry no raw HTML and no HTML entities, skipping code.\n\n**Raw HTML disappears from the page.** A block of HTML written into the Markdown\nis missing from the built page, and the source looks fine. Gruber's syntax lets\nHTML stand anywhere in the text, but a converter is free to refuse it: Hugo's\n`unsafe` setting for Goldmark is off by default, so raw HTML mixed into Markdown\nis not rendered, and GFM escapes a short list of tags such as `script` and\n`iframe` so that they print as text. Reach for what the generator offers\ninstead, a shortcode or a render hook in Hugo, or turn the setting on\ndeliberately and accept what it lets through.\n\n**The linter passes what it was told to ignore.** A Markdown file with broken\nstructure gets through review because markdownlint reports nothing. The rules\nthat would have caught it were switched off in its configuration, with no reason\nwritten down. This site's development rules record that markdownlint once sat in\na JSON file with six rules disabled and no comments, and that when the six were\nmeasured, two were hiding real defects. Write the reason beside every disabled\nrule, in a format that can hold a comment, so that the next person can disagree\nwith it.\n\n## Further reading\n\n- [CommonMark Spec](https://spec.commonmark.org/) — the specification, rule by\n  rule, each one tied to examples of input and the HTML it must produce.\n- [CommonMark](https://commonmark.org/) — why a specification was needed, how\n  implementations diverged, and who maintains it.\n- [Markdown, by John Gruber](https://daringfireball.net/projects/markdown/) —\n  the original description, the design goal and the Perl script.\n- [Markdown: Syntax](https://daringfireball.net/projects/markdown/syntax) —\n  Gruber's own account of the syntax, including the rule for inline HTML.\n- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) — GitHub's\n  dialect as a superset of CommonMark, with each extension marked.\n- [RFC 7763: The text/markdown Media Type](https://www.rfc-editor.org/rfc/rfc7763)\n  — the media type, its required `charset` and its `variant` parameter.\n\n\u003chttps://engineer.company/glossary/markdown/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"Where Markdown came from, why one file can render two ways, how CommonMark pins the syntax down, and the mistakes that print asterisks as text.","formats":{"gemtext":"https://engineer.company/glossary/markdown/index.gmi","gopher":"https://engineer.company/glossary/markdown/gophermap","html":"https://engineer.company/glossary/markdown/","json":"https://engineer.company/glossary/markdown/index.json","markdown":"https://engineer.company/glossary/markdown/index.md","pdf":"https://engineer.company/glossary/markdown/index.pdf"},"kind":"page","language":"en","title":"What is Markdown?","url":"https://engineer.company/glossary/markdown/","version":1}