Markdown, and which flavor you are writing

Markdown is a plain-text syntax that converts cleanly to HTML, designed so the source stays readable even before it is rendered. The catch is that there is no single Markdown. John Gruber's 2004 original left enough ambiguity that implementations diverged, which is why the same document can render three different ways in three different tools.

Two dialects matter in practice. CommonMark is the strict specification that settled the ambiguities. GitHub-Flavored Markdown builds on it and adds the features people actually reach for: tables, strikethrough, task lists, and automatic linking of bare URLs. This converter targets GFM, because that is what a README, a pull request description, and most documentation sites expect.

The syntax worth memorizing

Most of Markdown is obvious after one look. These are the parts that are not:

| Tool   | KD | Time |
|:-------|:--:|-----:|   <- colons set column alignment
| Base64 | 18 | 3h   |

- [x] a completed task
- [ ] an open one
  - [ ] indent two spaces to nest

Trailing two spaces force a line break.  
This line is part of the same paragraph.

```js
// language after the fence enables highlighting
```

The alignment colons in a table's delimiter row are the detail people look up most often. A colon on the left aligns left, on the right aligns right, on both centers the column.

Why the HTML output is escaped

Most converters pass raw HTML in the source straight through to the output. That is convenient and it is also how a Markdown document becomes a cross-site scripting vector: a<script>tag, anonerrorattribute, or ajavascript:link in a user-submitted comment executes on whatever page renders it.

This converter escapes every text node during conversion and can only emit a fixed allowlist of tags, so dangerous markup in the source arrives in the output as visible text. The trade-off is real and deliberate: you cannot drop a raw<div>into your Markdown and have it render. In exchange, output you paste into a page can never carry a payload.

Doing it in code

In JavaScript, the two standard choices aremarkedfor a single fast call and theremarkecosystem when you need to transform the document tree. In React, reach forreact-markdownwithremark-gfm, which renders to real components and skips thedangerouslySetInnerHTMLproblem entirely. Whatever you pick, if the Markdown comes from a user, run the output through a sanitizer such as DOMPurify before it reaches the DOM. A converter and a sanitizer are different jobs, and most converters do not do the second one.

Where Markdown quietly bites

Underscores inside words. A variable nameduser_id_valuecan turn half your sentence italic, because the underscores read as emphasis markers. Wrap identifiers in backticks and the problem disappears.

Lists that refuse to nest. Nesting depends on indentation, and different parsers disagree about how much is enough. Two spaces per level is the safest choice; tabs and four-space indents are where a nested list silently flattens or becomes a code block instead.

Missing blank lines. Markdown uses blank lines to separate blocks. A table, list, or heading pressed directly against the paragraph above it often gets absorbed into that paragraph. If something is not rendering, an absent blank line is the first thing to check.