Markdown is a family of plain-text syntaxes, not one complete language with one universal renderer. John Gruber's original design prioritized readable source and simple HTML output; CommonMark specifies a compatible core, while GitHub Flavored Markdown (GFM), MDX, R Markdown, and editor-specific dialects add different features. A reliable document declares its flavor, renderer, extensions, sanitization policy, and target output.

Key Takeaways

  • Learn CommonMark first, then check the target platform's flavor. Tables, task lists, footnotes, math, Mermaid, raw HTML, and JSX are not all core Markdown.
  • Markdown source is not automatically safe HTML. Escape or sanitize rendered output and restrict URL schemes, attributes, embedded content, and raw HTML.
  • HTML-to-Markdown and Markdown-to-HTML conversions can lose structure, styling, metadata, whitespace, or behavior. Preserve an original source and test round trips.
  • Use semantic headings, descriptive links, meaningful alternative text, keyboard-accessible HTML, and reduced reliance on color or layout hacks.
  • Code fences, table alignment, footnotes, and line breaks depend on parser details. Test examples with the exact renderer used in production.

Flavors and Compatibility

Flavor or extension What it is Typical additions or behavior
CommonMark A specified core syntax and parsing model Headings, paragraphs, emphasis, lists, links, images, quotes, code, thematic breaks
GFM GitHub's documented extension set Tables, task list items, strikethrough, autolinks, fenced code behavior
MDX Markdown combined with JSX/component syntax Components and expressions that require a trusted build pipeline
R Markdown Markdown plus executable document tooling Code chunks, output, and reproducible report workflows
Math/Mermaid extensions Renderer integrations Formula or diagram blocks outside core Markdown

“Supported Markdown” is incomplete without naming the parser and enabled extensions. A document that renders in GFM may display as literal punctuation in a CommonMark-only parser.

CommonMark Core

Headings and Paragraphs

ATX headings use one to six # characters followed by a space:

code 
## A level-two heading
### A level-three heading

Setext headings use underlines for levels one and two:

code 
Heading one
===========

Heading two
-----------

Separate paragraphs with a blank line. A single newline may remain a space in the rendered paragraph. For a hard line break, use two trailing spaces or a backslash where the renderer supports the rule; an explicit <br> is HTML and may be disallowed or sanitized.

Use heading levels to represent document structure, not visual size. Keep one meaningful page heading where the host document permits it, and do not insert a lower-level heading solely to obtain smaller text.

Emphasis and Inline Code

markdown 
*italic* and _italic_
**bold** and __bold__
***bold italic***
`inline code`
\*literal asterisks\*

Delimiter rules depend on surrounding punctuation and nesting. Put backticks around command names, paths, and identifiers; use a longer fence when the code itself contains backticks.

Lists and Quotes

markdown 
- First item
- Second item
  - Nested item

1. First step
2. Second step

> A quoted paragraph.
>
> > A nested quote.

Ordered-list numbering may be normalized by a renderer, but use meaningful source numbering when readers will inspect or maintain the file. Keep list indentation consistent and test nested code blocks.

markdown 
[CommonMark specification](https://spec.commonmark.org/)

[Long reference][spec]

[spec]: https://spec.commonmark.org/ "CommonMark"

![A terminal showing a test result](./test-result.png)

Link text should describe the destination rather than say “click here.” Prefer https and validate schemes; reject javascript:, unexpected data:, and unsafe custom protocols unless an explicit policy requires them.

An image's alternative text should convey its purpose or essential information. Use empty alt text only for a genuinely decorative image, and provide a text alternative for diagrams, charts, or image-only instructions. An image URL may also need an explicit rights, retention, and privacy review.

Thematic Breaks

Three or more matching -, *, or _ characters on a line can form a thematic break:

markdown 
---

Avoid using a thematic break as a substitute for a missing heading or semantic section.

Code, Tables, and Footnotes

Fenced Code

Use a fenced block with an optional language label:

markdown 
```python
print("hello")
```

The label is a hint to the highlighter, not a guarantee that the code compiles or that every renderer recognizes it. Never rely on highlighting for meaning; keep code readable without color. Mark pseudocode as pseudocode and pin commands or dependency versions when reproducibility matters.

Tables

Tables are a GFM-style extension in many platforms:

markdown 
| Field | Meaning |
| :--- | :--- |
| `id` | Stable identifier |
| `name` | Display label |

Escape or code-wrap literal pipes inside cells, keep headers meaningful, and provide a linear alternative when a table is too wide or conveys an essential relationship that screen readers cannot easily follow. Tables should not be used only for page layout.

Footnotes

Footnotes use an extension supported by some parsers:

markdown 
An evidence note[^source].

[^source]: Identify the source and access date.

Check generated IDs, keyboard navigation, back-links, and localization. If the target renderer has no footnote support, use ordinary links or an explicit references section.

Raw HTML and Safe Rendering

Many parsers pass selected HTML through:

html 
<details>
<summary>Implementation note</summary>
The content is still subject to the host's HTML policy.
</details>

Raw HTML is not a security boundary. A service that accepts untrusted Markdown should parse it with a known renderer, sanitize the resulting HTML with an allowlist, remove event-handler attributes and dangerous URLs, restrict iframe/img/svg behavior, and apply a suitable Content Security Policy. Do not execute embedded scripts, JSX, or template expressions from untrusted documents.

align, inline styles, and arbitrary dimensions may be ignored or removed. Prefer semantic HTML and CSS owned by the host application. Do not claim that a Markdown parser alone prevents XSS.

Math, Mermaid, and Other Extensions

Math delimiters such as $...$ and $$...$$, Mermaid diagrams, syntax highlighting, and custom directives are renderer features. Define:

  • the parser and extension versions;
  • whether formulas are converted to accessible MathML or have text alternatives;
  • whether diagrams are rendered server-side or client-side;
  • whether diagram text, links, or SVG output is sanitized;
  • the fallback for readers and export formats that do not support the extension.

Mermaid source is not automatically an image and may not be safe to execute or render from untrusted input. Do not rely on color alone in diagrams; include labels and a textual explanation.

Conversion Boundaries

HTML and Markdown have different expressive power. Conversion can lose CSS selectors, ARIA relationships, nested structures, comments, IDs, footnotes, math, interactive behavior, and exact whitespace. HTML may also contain unsafe elements that a converter must remove rather than preserve.

A defensible conversion workflow is:

  1. identify the source trust level and preserve the original;
  2. parse with a standards-aware library rather than regular expressions;
  3. map headings, lists, links, images, tables, and code explicitly;
  4. sanitize output for its destination context;
  5. render and compare representative fixtures, including malformed input;
  6. record parser version, options, source hash, output hash, and review result.

Markdown-to-HTML output still requires escaping and sanitization. HTML-to-Markdown is not proof of semantic or visual equivalence.

Accessibility and Publishing

  • Use a logical heading hierarchy and descriptive link labels.
  • Provide alt text, captions, transcripts, or data tables for visual content.
  • Keep keyboard focus visible and ensure generated disclosures and controls are operable without a pointer.
  • Do not communicate status with color alone.
  • Check contrast, code readability, table overflow, zoom/reflow, and reduced-motion behavior in the host UI.
  • Preserve language metadata and use fenced code labels that assist readers and tools.

Markdown cannot guarantee accessibility by itself; the renderer, CSS, HTML structure, content, and assistive technology path all matter.

Authoring Checklist

  1. Declare the target flavor and renderer.
  2. Use core syntax when portability matters.
  3. Test links, images, code fences, tables, footnotes, and extensions in the target environment.
  4. Validate and sanitize untrusted Markdown before publishing.
  5. Keep source files, licenses, image rights, and conversion metadata.
  6. Run link, accessibility, and rendered-output checks in CI.
  7. Review exported HTML for scripts, URLs, ARIA structure, and disclosure behavior.

Frequently Asked Questions

Is Markdown standardized?

There is no single universal Markdown language. CommonMark specifies a core, while GFM and other tools add extensions. Name the flavor and renderer whenever compatibility matters.

Are Markdown files safe to render?

Not automatically. Raw HTML, URLs, images, SVG, extensions, and generated HTML can create security or privacy risks. Parse and sanitize according to the destination context.

Are Markdown and HTML conversions lossless?

Generally no. Interactive behavior, styling, metadata, whitespace, footnotes, math, and accessibility relationships may be lost. Test a constrained subset and retain the source of truth.

Is a fenced language label executable?

No. It is normally a highlighting hint. A build system or notebook extension may add execution behavior, so inspect the pipeline before treating a document as code.

Why does a table or footnote work on one site but not another?

Those features are extensions or have different parser rules. Check the target flavor, enabled plugins, version, and generated HTML.

Primary Sources

Conclusion

Markdown is valuable because its source is portable and inspectable, not because every renderer behaves identically. Choose and document a flavor, keep semantics ahead of decoration, sanitize untrusted output, preserve accessibility, and test conversions with the exact publishing pipeline. That discipline prevents a “cheat sheet” from becoming a compatibility or security trap.