Why Is GitHub Markdown Not Rendering? 10 Causes & Fixes

GitHub strictly requires at least one space between the hash symbol and your heading text. Without it, the line is treated as a paragraph.

#Heading Without Space
##Another Broken Heading

# Heading 1
## Heading 2
### Heading 3

GFM tables require: (1) a header row, (2) a separator row with at least one dash per cell, and (3) consistent pipe characters. Missing any of these causes the table to render as plain text.

| Feature | Status |
| Engine | Ready |

| Feature | Status |
| :--- | :---: |
| Engine | ✅ Ready |
| Tests | ✅ Passing |

Images using relative paths work in VS Code local preview but break on GitHub because they are resolved against the repo root on the default branch — not the filesystem directory you are editing in.

![Screenshot](screenshots/app.png)
![Logo](../assets/logo.png)

![Screenshot](docs/screenshots/app.png)

<!-- Or use the raw GitHub URL: -->
![Logo](https://raw.githubusercontent.com/user/repo/main/assets/logo.png)

GFM task lists require: a dash, then a space, then brackets with a space inside (unchecked) or "x" (checked), then another space, then the task text.

-[] Task not done
-[x]Task done
* [ ]Also broken

- [ ] Unchecked task
- [x] Checked task
- [ ] Another item

If you open a triple-backtick code fence but forget to close it, everything below it is treated as a code block — producing raw monospace text for the entire rest of the document.

```javascript
const x = 1;
// Forgot to close!

## This heading disappears
And all this text becomes code.

```javascript
const x = 1;
// Properly closed
```

## This heading renders correctly
And this text is normal.

When you mix raw HTML with Markdown in GitHub READMEs, HTML blocks must be surrounded by blank lines. If your Markdown immediately follows an HTML closing tag, it will be consumed into the HTML block and not rendered.

<div align="center">
  <img src="logo.png">
</div>
## Getting Started
This paragraph breaks.

<div align="center">
  <img src="logo.png">
</div>

## Getting Started

This paragraph renders correctly.

GitHub only renders Mermaid in .md files on github.com — not in raw.githubusercontent.com links, GitHub Pages by default, or GitHub wikis without configuration. The code block must be tagged ```mermaid (not ```mermaid-js or similar).

```mermaid-js
flow LR
  A --> B
```

```mermaid
flowchart LR
  A[Start] --> B[End]
```

GitHub added native math support in 2022. Use $...$ for inline and $$...$$ for block equations. Some older README files use \( \) or \[ \] — these are NOT supported on GitHub.

\( E = mc^2 \)
\[ \sum_{i=1}^{n} x_i \]

Inline: $E = mc^2$

Block:
$$
\sum_{i=1}^{n} x_i
$$

GitHub introduced coloured alert callouts in 2023 using a specific blockquote syntax. The keyword must be uppercase and use the exact bracket format shown — lowercase or other brackets will render as a plain blockquote.

> [note]
> This is a note.

> [!note]
> Lowercase does not work.

> [!NOTE]
> Informational callout.

> [!WARNING]
> Warning callout.

> [!IMPORTANT]
> Critical callout.

Footnotes ([^1]) are supported in GitHub READMEs and Discussions but NOT in Issue comments or Pull Request descriptions. They will render as literal bracketed text in those contexts.

<!-- In a PR comment: -->
See footnote[^1].
[^1]: This is the footnote.

<!-- In a README.md file: -->
See footnote[^1].

[^1]: This renders correctly in README files.