Why there is more than one Markdown
Markdown began as a script with a short informal description, and for a decade every platform that adopted it filled the gaps its own way. Does a single line break make a paragraph break? Can a list start without a blank line before it? What happens to an underscore inside a word? Each answer was a coin toss, and the coins landed differently on GitHub, Reddit, Stack Overflow and in every static site generator.
CommonMark exists to settle those questions, and most converters built in the last several years follow it, usually with GitHub's extensions for tables and strikethrough added on. If you write to CommonMark you will render correctly almost everywhere. If you lean on a platform's quirk, you will find out the day you paste the file somewhere else.
What every converter gets right
Headings with hash marks. Paragraphs separated by a blank line. Emphasis with asterisks. Links in the square-bracket-then-parenthesis form. Fenced code blocks with three backticks. Ordered and unordered lists with a blank line before them. Block quotes with a leading angle bracket. Horizontal rules.
Write with those and the output is predictable. The Markdown to HTML converter follows CommonMark with the GitHub extensions, shows the rendered result beside the HTML, and is a quick way to confirm that a document behaves before it goes into a CMS.
Five places it breaks
Single line breaks. In CommonMark a lone newline inside a paragraph is a space, not a break. Many chat and note apps treat it as a break. Text that looked fine in one renders as run-together sentences in the other. Two spaces at the end of a line, or a backslash, forces a break everywhere; a blank line makes a paragraph.
Lists without a blank line before them. Older converters start a list on the line immediately after a paragraph. CommonMark often does not, and the list becomes part of the paragraph. A blank line before every list is the habit that avoids it.
Nested lists and indentation. How many spaces make a nested item has varied between two, four, and "aligned with the content of the parent". CommonMark chose the last. Four spaces works almost everywhere; two does not.
Raw HTML. Markdown allows HTML inline, and whether a given converter passes it through, escapes it or strips it depends on where the output is going. A converter rendering untrusted input should escape it, which the tool here does, so a pasted script tag becomes visible text rather than running.
Tables. Not in CommonMark at all. The pipe-table syntax comes from GitHub's extension and is widely but not universally supported, and alignment colons are the part most likely to be ignored.
The invisible characters that break everything
Text pasted out of a word processor carries curly quotes, non-breaking spaces and the occasional zero-width character. A non-breaking space where Markdown expects a normal one stops a heading from being a heading. A curly quote inside a code span renders as a curly quote in the code. These are not Markdown problems but they present as them, and the text cleaner removes them before the converter sees the file.
Headings also become URL slugs on most platforms, and a heading with punctuation produces an ugly or broken anchor. The slug generator shows what a heading will turn into, which is worth knowing before a document with sixty of them is published.
Before publishing
Render it in a CommonMark converter and read the output, not the source. Check the first list after a paragraph, the first nested list, and anywhere a line break was meant to be a break. Check that raw HTML did what you intended. Run the prose through the readability checker if the audience is general, because Markdown's ease of writing produces long sentences nobody notices in a monospace editor.
Questions people ask
Because Markdown had no formal specification for years and platforms filled the gaps differently. CommonMark now defines the behaviour most modern converters follow. Writing to it, with blank lines before lists and four-space nesting, renders consistently almost everywhere.
A single newline inside a paragraph is a space in CommonMark, not a break. Some apps treat it as a break, which is where the expectation comes from. End the line with two spaces or a backslash for a hard break, or leave a blank line for a new paragraph.
Usually there is no blank line between the preceding paragraph and the first item, so the converter treats the items as part of the paragraph. Add a blank line before the list. For nested items, indent by four spaces.
Not in the CommonMark core. Pipe tables are a GitHub extension that most, but not all, converters support. Where they are supported, keep them simple: one header row, a separator row, no merged cells, and expect alignment colons to be ignored in some places.
It depends on the converter. Markdown permits raw HTML, and a converter that passes it through will execute any script it contains when the output is displayed. A converter that escapes raw HTML, as the one here does, renders it as visible text instead. For untrusted input, escaping is the only safe choice.
CommonMark with the GitHub extensions for tables and strikethrough. It renders correctly on GitHub, in most static site generators and in most editors. Avoid platform-specific syntax such as custom containers or footnote variants unless the document will only ever live on that one platform.

