Markdown Not Rendering? Fix Line Breaks, Tables and Lists

A single newline inside a paragraph counts as a space. Two lines typed one under the other render as one line. This is the most common surprise, and it is what the specification says.

• End the line with a backslash \ to force a break.
• End the line with two spaces. This works, but many editors strip trailing spaces on save, and the break silently disappears.
• Leave an empty line to start a new paragraph instead.
• Write <br> where the site allows HTML.

Why does the same text work in a GitHub comment but not in a README? GitHub renders issue, pull request and discussion comments with every newline as a break. Markdown files follow the specification. Parsers expose the same switch:

import { marked } from "marked";

marked.parse("one\ntwo");                   // "<p>one\ntwo</p>" - one line on screen
marked.parse("one\ntwo", { breaks: true }); // "<p>one<br>two</p>"

A GFM table needs a delimiter row directly under the header, with the same number of cells as the header. Without it, the whole block stays plain text.

| Name | Role  |
| :--- | ----: |
| Ana  | Admin |

• No | --- | row under the header: plain text.
• Two header cells but one delimiter cell: plain text.
• A | inside a cell splits it, even inside backticks. Write \| instead.
• Colons set alignment: :--- left, :---: centre, ---: right.

A missing blank line before the table is rarely the cause. A table directly under a paragraph line still renders in GFM.

A sub-item belongs to its parent only when it is indented to where the parent's text starts. After - that is two spaces. After 1. it is three, and after 10. it is four.

1. Install
  - two spaces: a separate list after the numbered one

1. Install
   - three spaces: nested under "Install"

Four spaces nests correctly under both - and 1. items, which is why many style guides use it everywhere.

In GFM an underscore inside a word is literal, so my_var_name stays as written. An asterisk inside a word still starts emphasis: un*frigging*believable comes out with the middle in italics. Put identifiers in backticks, or escape the character with a backslash.

An opening fence of three backticks with no closing fence runs to the end of the document, so every heading below it shows as code. Close every fence. To show a fence inside a code block, make the outer fence longer, or use ~~~:

````markdown
```js
console.log("inner fence");
```
````

Text indented by four spaces after a blank line also becomes a code block. If a paragraph suddenly shows in a monospace box, check its indentation.

Inside an HTML block such as <div> or <details>, Markdown is not processed until a blank line ends the block. Put an empty line after the opening tag and another before the closing tag, and **bold** inside becomes bold.

Some tags never appear at all. GitHub removes scripts, styles, iframes and forms from rendered Markdown, so HTML that works in a local file can vanish from a README. The Markdown editor uses a similar allow-list, so you see the problem before you publish.

GitHub and GitLab draw a code block fenced with mermaid as a diagram. Plain CommonMark renderers show the same block as code, so first check that the place you publish supports Mermaid. When it does and the diagram still fails, the cause is usually one of these:

• The first line must name the diagram type, such as graph TD, flowchart LR or sequenceDiagram. Without it Mermaid reports that no diagram type was detected.
• Brackets and parentheses inside a label break the parser: A[Status (200)] fails. Quote the label: A["Status (200)"].
• A node named end in lower case ends the flowchart early. Write End or END.

#Title without a space stays as plain text. Write # Title. The same applies to every level up to ######.