Syntax
Markdown starts with readable text and adds small marks for structure. These are the marks worth remembering before thinking about dialects.
Core marks
Markdown is easiest when the marks feel like hints in plain text, not commands in a programming language.
# Heading Start a line with one or more hash marks. First paragraph\n\nSecond paragraph Separate blocks with a blank line; ordinary text stays ordinary. *italic* and **bold** Wrap words when a phrase needs emphasis. [text](https://example.com) Put readable link text in brackets and the target in parentheses.  Describe the image in brackets and put the source in parentheses. - item\n1. item Start lines with bullets or numbers. > quoted text Prefix quoted lines with a greater-than sign. `code` Use backticks when text should be read as code. Common extensions
These forms are useful, but they depend more on the renderer or publishing system.
``` Fenced code blocks Common in modern Markdown; language labels and highlighting vary. | | Tables Common in GFM-style Markdown, but not part of original Markdown. - [ ] Task lists Useful in developer tools and note apps, still extension behavior. [^1] Footnotes Supported by some dialects and platforms, not by core Markdown. --- / $ Metadata and math Usually handled by publishing tools, math renderers, or platform settings. Core marks
Use hash-prefixed headings for portable document structure.
# Page title
## Section title
### Subsection title
ATX-style headings are broadly portable. Exact heading IDs and anchor links vary by renderer.
Core marks
Use blank lines to separate paragraphs and blocks.
First paragraph.
Second paragraph after a blank line.
Ordinary paragraphs are the most portable part of Markdown. Single line breaks inside a paragraph may render differently by setting or platform.
Core marks
Use asterisks or underscores for italic and bold text.
This sentence has *italic text* and **bold text**.
This one uses _italic text_ and __bold text__.
Asterisks and underscores are both common. Asterisks are often easier to read around words that contain underscores.
Core marks
Use inline links and images when the target should be visible in the source.
Read the [Markdown project page](https://daringfireball.net/projects/markdown/).
The syntax is portable, but relative paths, image dimensions, and security rules are platform behavior.
Core marks
Use blank lines around complex list content to keep nesting readable.
- First item
- Second item
- Nested item
- Another nested item
1. First step
2. Second step
3. Third step
List parsing is mature across major dialects, but paragraph spacing inside lists can change the output.
Common extensions
Use pipe tables for simple grids where GFM-style syntax is supported.
| Feature | Portable? | Note |
| --- | --- | --- |
| Headings | Yes | Broad support |
| Tables | Depends | Common in GFM-style Markdown |
| Math | Depends | Usually platform-specific |
Tables are not part of original Markdown or core CommonMark. Treat them as an extension unless the target platform documents support.
Common extensions
Use task list items for checklists on platforms that support them.
## Release checklist
- [x] Draft copy
- [ ] Check preview
- [ ] Publish
Task list markers are widely recognized in developer tools, but they are still extension behavior rather than original Markdown.
Common extensions
Use fenced code blocks for readable code examples with optional language labels.
```js
const format = "Markdown";
console.log(`${format} preview`);
```
The fenced block syntax is broadly supported now, but language names and highlighting output depend on the renderer.
Core marks
Use blockquotes for quoted passages, notes, or callout-like text.
> Markdown should be readable as plain text first.
>
> The rendered output is the second layer.
Plain blockquotes are portable. Special callout syntax such as note boxes is platform-specific.
Common extensions
Use footnotes only when the target renderer explicitly supports them.
A short sentence can carry a footnote.[^1]
[^1]: Footnotes are supported by some Markdown dialects and platforms.
Footnotes are extension syntax. Some GFM-compatible JavaScript parsers do not support them without an extra plugin.
Publishing tools
Use frontmatter for static site metadata when the publishing tool expects it.
---
title: Markdown note
description: A short page summary
tags:
- markdown
- reference
---
# Markdown note
Frontmatter is usually consumed by a site generator or content system, not by Markdown itself.
Publishing tools
Use math delimiters only after checking the target platform.
Inline math: $E = mc^2$
Block math:
$$
f(x) = x^2 + 2x + 1
$$
Math is not a core Markdown feature. Delimiters and rendering depend heavily on the target platform.
No matching syntax.