Markdown is everywhere — but Markdown is not the same everywhere. If you’ve ever carefully written a document with footnotes, custom HTML, or a nice callout block, only to paste it into a different tool and watch it break, you know the pain.

This guide is a practical reference for which Markdown features work in the tools most developers and technical writers actually use. Not theory — just what works, what doesn’t, and what you need to do differently on each platform.

Quick Comparison Table

Feature GitHub GitLab Notion Obsidian Confluence VS Code
Basic formatting (bold, italic) ✅ ✅ ✅ ✅ ✅ ✅
Headings ✅ ✅ ✅ ✅ ✅ ✅
Fenced code blocks ✅ ✅ ✅ ✅ ✅ ✅
Syntax highlighting ✅ ✅ ✅ ✅ ⚠️ limited ✅
Tables ✅ ✅ ✅ ✅ ✅ ✅
Task lists ✅ ✅ ✅ ✅ ❌ ✅
Strikethrough ✅ ✅ ✅ ✅ ✅ ✅
Footnotes ✅ ✅ ❌ ✅ ❌ ⚠️ varies
Inline HTML ✅ ✅ ❌ ⚠️ partial ❌ ✅
Emoji shortcodes (:smile:) ✅ ✅ ✅ ✅ ✅ ❌
Callouts / Admonitions ✅ (alerts) ⚠️ ✅ (native) ✅ ✅ ❌
Math / LaTeX ✅ ✅ ✅ ✅ ⚠️ plugin ⚠️ extension
Definition lists ❌ ✅ ❌ ❌ ❌ ❌
Mermaid diagrams ✅ ✅ ❌ ✅ (plugin) ⚠️ plugin ✅ (extension)
Auto table of contents ✅ (sidebar) ✅ ✅ (native) ✅ (plugin) ✅ ❌

✅ = fully supported   ⚠️ = partial/requires setup   ❌ = not supported

Now let’s go platform by platform.

GitHub

GitHub uses GitHub Flavored Markdown (GFM), which extends CommonMark with a set of additional features. It’s the most widely referenced flavor of Markdown and the one most tools try to be compatible with.

What GitHub does well

Tables work without any special setup:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell     | Cell     | Cell     |

Task lists render as interactive checkboxes in issues and pull requests:

- [x] Done
- [ ] Not done

Syntax-highlighted code blocks — just add the language name after the opening backticks:

```python
def hello():
    print("Hello, world!")
```

Alerts/callouts were added in 2023 and use a blockquote-based syntax:

> [!NOTE]
> This is a note.

> [!WARNING]
> This is a warning.

> [!TIP]
> This is a tip.

Mermaid diagrams work directly in code fences:

```mermaid
graph TD;
    A-->B;
    B-->C;
```

Footnotes are supported:

Here is a claim.[^1]

[^1]: Here is the footnote.

GitHub gotchas

  • Anchor link generation: GitHub lowercases all characters and replaces spaces with hyphens. Special characters (except hyphens and underscores) are removed. ## API & SDK becomes #api--sdk.
  • Inline HTML is allowed but script tags and most event attributes are stripped for security.
  • Indentation in lists matters — use 4 spaces (not 2) if you want nested paragraphs inside a list item.
  • Definition lists (<dl>, <dt>, <dd>) are not part of GFM — use a table instead.

GitLab

GitLab also uses GFM as a base but adds its own extensions, some of which are quite powerful.

GitLab extras

  • Superscript and subscript: x^2^ and H~2~O
  • Color chips: inline hex colors like `#FF0000` render a color swatch in merge requests
  • Diagrams: Mermaid, PlantUML, and Kroki are all supported
  • Definition lists: ✅ (unlike GitHub)
  • Table of contents: Add [[_TOC_]] anywhere in a document to auto-generate one
  • Markdown in epics/issues: supports most GFM plus GitLab-specific references (#123, @username, !456)

GitLab gotchas

  • Many extended features only work in GitLab wiki pages and repository files, not in issue descriptions everywhere.
  • Callout blocks aren’t native like GitHub’s [!NOTE] syntax — you need to use raw HTML or CSS classes.

Notion

Notion has its own Markdown-like editor that isn’t really Markdown — it’s a block-based editor that supports Markdown shortcuts for input but stores content internally as blocks.

What Notion supports

  • Basic formatting (bold, italic, strikethrough, inline code)
  • Headings, bulleted and numbered lists, task lists
  • Code blocks with syntax highlighting (choose language from dropdown)
  • Tables (as a native block type)
  • Math blocks using LaTeX (via /math or /equation)
  • Native callout blocks (different from Markdown syntax)
  • Toggles (collapsible sections) — no Markdown equivalent

Notion Markdown import/export

When you import Markdown into Notion, it converts what it can into blocks. When you export to Markdown, it converts blocks back — but you’ll lose Notion-specific features (toggles become plain text, callouts may simplify).

<!-- This works when imported into Notion -->
**Bold** and *italic* and ~~strikethrough~~

# Heading 1
## Heading 2

- [x] Task done
- [ ] Task pending

| Col A | Col B |
|-------|-------|
| 1     | 2     |

Notion gotchas

  • No footnotes — there’s no native footnote block.
  • No inline HTML — all HTML is stripped.
  • Emoji shortcodes work (:thumbsup: renders 👍) but not all codes.
  • Callout blocks are native Notion features — they don’t map to any standard Markdown syntax. When exporting, they typically become blockquotes.
  • Links behave differently: Notion links to other Notion pages use @ mentions in the editor, not Markdown links.

Obsidian

Obsidian uses CommonMark as its base with GFM extensions added on top. It’s designed for personal knowledge management, so it has features optimized for linking between notes.

Obsidian-specific features

Wiki-links for linking between notes:

[[Another Note]]
[[Folder/Note|Custom display text]]

Callouts use a slightly different syntax from GitHub:

> [!NOTE]
> This is a note callout.

> [!WARNING] Custom title
> This is a warning with a custom title.

Tags in frontmatter and inline:

---
tags: [markdown, writing]
---

This is #tagged inline too.

Footnotes are fully supported:

Here is text.[^note]

[^note]: Footnote content.

Math works with $ (inline) and $$ (block):

Inline: $E = mc^2$

Block:
$$
\frac{d}{dx}\left( \int_{0}^{x} f(u)\,du\right)=f(x)
$$

Obsidian gotchas

  • Inline HTML is partially supported — basic tags like <u>, <br>, <sup>, <sub> usually work. Script tags and styles are blocked.
  • Mermaid diagrams require the Mermaid plugin (or are built-in depending on your Obsidian version).
  • Wiki-links don’t work outside Obsidian — if you share .md files with others, these links will break.
  • Strikethrough requires GFM mode (enabled by default).
  • The Live Preview mode and Source mode render things slightly differently — always check your callouts and tables in reading view.

Confluence

Confluence has two editors: the legacy wiki markup editor and the newer Confluence Cloud editor (block-based). Markdown support depends on which you’re using.

Confluence Cloud (new editor)

Confluence Cloud supports importing Markdown via the / command — paste your Markdown and Confluence will convert it. Native Markdown authoring is limited; the editor is block-based.

Supported via import:

  • Headings, bold, italic, strikethrough
  • Ordered and unordered lists
  • Fenced code blocks
  • Tables (with caveats — complex tables may not import cleanly)
  • Links and images

Not supported or converted differently:

  • Task lists — become plain list items, not Confluence action items
  • Footnotes — dropped on import
  • Inline HTML — stripped
  • Callouts — become plain blockquotes

Confluence gotchas

  • Tables with merged cells will not import from Markdown at all — Markdown tables can’t represent cell merging.
  • Macros (like the info, warning, and note panels) are Confluence-specific and have no Markdown equivalent.
  • Syntax highlighting works in code blocks, but you need to select the language within the Confluence UI after importing.
  • If you’re on Confluence Data Center (self-hosted), the behavior varies by version and installed plugins.

VS Code

VS Code’s built-in Markdown preview renders CommonMark spec, not full GFM. It’s useful for quick previewing but has some limitations.

What works in VS Code preview

  • Headings, basic formatting, lists, links, images
  • Fenced code blocks (with syntax highlighting)
  • Tables
  • Strikethrough (via the markdown-it GFM extension, enabled by default)
  • Math (with the Markdown Math extension or built into newer VS Code versions)

What doesn’t work out of the box

  • Task list checkboxes don’t render as interactive checkboxes (they display correctly but aren’t clickable)
  • Footnotes require an extension
  • Emoji shortcodes (:smile:) are not rendered
  • Mermaid diagrams require the Markdown Preview Mermaid Support extension
  • GitHub-specific alert syntax (> [!NOTE]) requires the Markdown Alert extension
  • Markdown All in One — TOC generation, keyboard shortcuts, list editing
  • Markdown Preview GitHub Styling — makes preview look like GitHub
  • markdownlint — lints your Markdown for common errors
  • Markdown Preview Mermaid Support — diagram rendering

Writing Portable Markdown

If your documents need to work across multiple platforms, follow these rules:

Safe everywhere

# Headings (H1–H4)
**Bold** and *italic*
- Unordered lists
1. Numbered lists
[Links](https://example.com)
![Images](image.png)
`Inline code`
\`\`\`fenced code blocks\`\`\`
| Simple | Tables |

Use with caution (works in most places, not all)

~~Strikethrough~~       <!-- Not in some older renderers -->
- [x] Task lists       <!-- Breaks in Confluence, some renderers -->
[Link][ref]            <!-- Reference-style links work everywhere but are less common -->

Avoid for portability

[^footnote]            <!-- Only GitHub, GitLab, Obsidian -->
<div>HTML blocks</div> <!-- Stripped in Notion, Confluence -->
:emoji:                <!-- VS Code, older renderers don't support -->
> [!NOTE] alerts       <!-- Only GitHub, Obsidian -->
[[wiki-links]]         <!-- Only Obsidian -->

Tip: Use our tools to help

If you’re moving content between formats, our HTML to Markdown converter and Markdown to HTML tool can help bridge the gap. For table conversion, Markdown Table → CSV makes it easy to pull data into spreadsheets.

Summary

The short version:

  • Most portable: Basic formatting + tables + fenced code blocks work everywhere
  • GitHub is the safest bet for extended features (footnotes, task lists, alerts)
  • Notion and Confluence are block-based editors — they import Markdown but don’t author it natively; expect some feature loss
  • Obsidian is the most feature-rich for local Markdown authoring but has proprietary extensions that break portability
  • VS Code is CommonMark only — add extensions for anything beyond basics

For platform-specific deep dives, see also: