Markdown tables are not part of the specification. Neither are strikethrough, task lists or automatic linking of bare URLs — all four are extensions added by one widely used flavour and adopted by others, which is why a file that renders perfectly in one place shows raw pipe characters in another.
The original description from 2004 was prose rather than a grammar, and the reference implementation settled the ambiguities by behaving however it behaved. A strict specification arrived a decade later and deliberately left the extensions out.
What is actually in the core?
Less than most people assume.
| Feature | In the strict core |
|---|---|
| Headings, lists, links, emphasis | yes |
| Code blocks and blockquotes | yes |
| Inline HTML | yes |
| Tables | no — extension |
| Strikethrough | no — extension |
| Task list checkboxes | no — extension |
| Footnotes | no — extension |
The extensions are so widely implemented that they feel standard, and they are safe wherever the target is known. The risk appears when a file travels — into a different editor, a static site generator or an email client — and the extension is not there.
Inline HTML is the escape hatch and is disabled in many contexts for security reasons, so it is not a reliable substitute.
Why did my underscores italicise a variable name?
Because underscores inside a word are treated as emphasis by older parsers. A name written with internal underscores becomes a word with an italic middle, which is an ambiguity the strict specification fixed by requiring emphasis to sit at word boundaries.
Parsers that predate that fix are still in use, and a file passing through one gets mangled. Wrapping identifiers in backticks avoids it entirely and is the correct markup anyway.
Asterisks have the opposite reputation and the same underlying issue. Anything containing a literal asterisk or underscore needs escaping or a code span, and code spans are less work.
Why did my line breaks disappear?
Because a single newline is not a line break in the original design. Consecutive lines are joined into one paragraph, and a real break requires either a blank line for a new paragraph or two trailing spaces at the end of the line.
Trailing spaces as syntax is widely disliked precisely because they are invisible and stripped by many editors. Several flavours changed the rule so that a single newline breaks the line, which means the same file wraps differently depending on where it is read.
It is the reason a table written with its rows on separate lines works and the same table joined into one paragraph does not. A table is a block, and its rows have to be consecutive lines.
What breaks when HTML is minified?
Spacing between inline elements. A space between two inline tags renders as a visible space, so removing all whitespace between elements changes the output — words run together where they used to be separated.
Block-level elements do not have this problem, which is why a minifier has to know the difference rather than treating the document as text. A tool that collapses whitespace indiscriminately produces valid HTML that looks wrong.
Comments are safe to strip except for the conditional ones some legacy tooling still reads, and attribute quotes can be removed only where the value has no spaces or special characters. None of it is as free as minifying a stylesheet.
When do you need to decode entities?
Whenever text has been through a system that escaped it and something failed to unescape it on the way back. The symptom is an ampersand and a word appearing literally on the page where a character should be.
Double encoding is the usual cause: text escaped once, stored, then escaped again on output, so the entity’s own ampersand became an entity. Decoding twice recovers it, and finding where the second escape happened prevents it recurring.
The reverse operation matters for anything user-supplied going into a page, which the encoding article covers alongside the other escaping questions.
What is Markdown genuinely good at?
Being readable before it is rendered. The syntax was designed so that a plain text file reads naturally with the markup in it, which is why it took over documentation, notes and commit messages rather than the richer formats that preceded it.
That constraint is also its ceiling. Anything needing precise layout, columns or a specific typeface is outside what the syntax can express, and reaching for inline HTML to get there usually means the wrong format was chosen.
The place it fits best is text that will be read as text at least as often as it is rendered — which describes most technical writing and very little marketing material.
Questions people ask
Which flavour should I write for? The one that will render it. If several might, stay in the strict core.
Can I mix HTML and Markdown? Usually, and Markdown inside an HTML block often stops being processed. Check rather than assume.
Why is my nested list flat? Indentation. Different parsers want two or four spaces, and tabs behave differently again.
Does converting to HTML lose anything? The source formatting. The conversion is one-way in practice, since the same HTML can come from several Markdown inputs.
Convert it and look at the result. Markdown to HTML does the rendering, the Markdown table generator and HTML table generator build the block that is easiest to get wrong by hand, the HTML formatter and minifier tidy the output, and HTML decode recovers text that has been escaped once too often.