Markdown Cheatsheet

Use # for headers (1-6 levels). Alternative syntax uses === for H1 and --- for H2. Paragraphs need a blank line between them. Markdown is designed to be readable as plain text.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Alternative Heading 1
=====================

Alternative Heading 2
---------------------

This is a paragraph. Just write
plain text. Leave a blank line
between paragraphs.

Two trailing spaces or a backslash at the end of a line create a hard line break (<br>). Without them, a single newline is a soft wrap that joins into one paragraph. Always leave a blank line to separate paragraphs.

First line  
Second line (two trailing spaces above)

Or use a backslash at end of line\
to force a line break.

Soft wrap without break:
just continue on the next line
and it joins into one.

Markdown has no official comment syntax, but HTML comments (<!-- -->) work in most renderers and are hidden in output. The [//]: # trick uses an empty link reference to add notes. Comments are still visible in the raw source.

<!-- HTML comments work in most Markdown -->

[//]: # (This is a comment)

[//]: # "Another comment style"

<!-- 
  Multi-line comment
  not rendered in output
-->

Four leading spaces turn text into a code block — beware accidental indentation. Indentation matters for nested lists (2-4 spaces per level). Tabs are usually treated as 4 spaces. Use spaces consistently to avoid rendering issues across parsers.

Paragraph one.

    This is an indented code block
    because of 4 spaces.

> Quoted text needs > prefix.

   Three spaces is just text
   (less than 4).

Three or more hyphens, asterisks, or underscores create a horizontal rule (<hr>). Hyphens are most common. Spaces between characters are allowed. For clarity, put blank lines around horizontal rules. Avoid confusing --- (rule) with # (heading).

---

***

___

   * * *

Text above

---

Text below

Double asterisks or underscores produce bold (<strong>). Asterisks are preferred since underscores do not work mid-word (snake_case). You can nest other emphasis inside bold. HTML <strong> tags work as a fallback.

**bold text**
__also bold__

**bold with *italic* inside**

<strong>HTML bold also works</strong>

**bold**

Single asterisks or underscores create italic (<em>). Asterisks work mid-word; underscores treat word-internal underscores as literal (so no_italic_here). Use <em> as a fallback. Italic is for emphasis, not just styling.

*italic text*
_also italic_

*italic*

<em>HTML italic</em>

normal *italic* normal

Triple asterisks/underscores produce both bold and italic. You can also nest them: bold containing italic or vice versa. Order does not matter for rendering but should be consistent for readability.

***bold and italic***
___also both___

**_bold and italic_**
*__bold and italic__*

combine **bold** and *italic*

Double tildes (~~) create strikethrough, part of GitHub Flavored Markdown and now widely supported. The HTML <del> and <s> tags are equivalent fallbacks. Standard (original) Markdown does not include strikethrough.

~~strikethrough~~

~~crossed out text~~

<del>HTML delete</del>
<s>HTML strikethrough</s>

~~done~~ and ~~pending~~

Double equals (==) for highlighting is an extension supported by some parsers (not in GFM core). The HTML <mark> tag works universally. Use highlighting sparingly to draw attention to key terms — overuse reduces its effect.

==highlighted text==

<mark>HTML mark</mark>

This is ==important== text.

Compare **bold**, *italic*, ==mark==.

Tilde (subscript) and caret (superscript) syntax (~ ~ and ^ ^) are extensions not in standard Markdown or GFM — supported by Pandoc, R Markdown, and a few others. For universal support, use HTML <sub> and <sup> or Unicode characters.

H~2~O is water

E = mc^2^

x^2^ + y^2^ = r^2^

1st^st^ January

CO~2~ emissions

Use -, *, or + for unordered list items — pick one and be consistent (- is most common). Indent 2-4 spaces for nested items. Mixing markers in the same list can cause issues in some parsers. One item per line.

- item one
- item two
- item three

* asterisk works too
+ plus sign also works

  - sub-item (indent 2 spaces)
  - another sub-item

Ordered lists use numbers followed by periods. The actual numbers do not need to be sequential — Markdown renumbers them. To start at a specific number, use that number first (10. starts at 10). Use 1. for all items to auto-number.

1. first
2. second
3. third

1. auto-numbered
1. still increments
1. third item

10. starts at 10
11. next

Indent nested list items by 2-4 spaces (4 is safest for mixed types). You can mix ordered and unordered lists at different levels. Deep nesting (3+ levels) hurts readability — consider restructuring. Keep indentation consistent.

1. top level
   - nested unordered
   - second nested
2. back to top
   1. nested ordered
   2. another
3. third top

- fruits
  - apple
    - granny smith
  - banana

Task list syntax (- [x] and - [ ]) is a GitHub Flavored Markdown extension. The checkbox renders as interactive on GitHub/GitLab. Works with both ordered and unordered lists. Great for READMEs, issue trackers, and progress tracking.

- [x] completed task
- [ ] incomplete task
- [ ] another todo

1. [x] done
2. [ ] not done

- [x] Write the docs
- [ ] Review PR
- [ ] Deploy

If list items are separated by blank lines, the list is 'loose' (each item wrapped in <p>). Without blank lines, it is 'tight' (no <p> wrappers). This affects spacing in HTML output. Add blank lines deliberately to control paragraph wrapping.

- tight item
- tight item
- tight item

- loose item

- loose item

- loose item

To include multiple paragraphs or block elements in a list item, indent the continuation by 4 spaces (or align with the list marker content). Blank lines separate the sub-blocks. This is essential for complex list structures but easy to get wrong.

- First item

  Second paragraph of first item.

- Second item

  > A blockquote inside a list item.
  >
  > Must be indented to align.

- Third item

Inline links use [text](url). Optional title in quotes appears as a tooltip on hover. Relative links work for internal site navigation. Anchor links (#id) jump to elements with matching id. The URL must not contain spaces — use %20 for spaces.

[link text](https://example.com)

[link with title](https://example.com "Title here")

[relative link](/about)

[anchor](#section-id)

Reference links keep text readable by separating the URL. Define references anywhere in the document ([ref]: url). Reference definitions are not rendered. The implicit form [text][] uses the text itself as the reference id. References can be reused.

[link text][ref]

[ref]: https://example.com "Optional title"

[link text][1]
[1]: https://example.com

[link text]
[link text]: https://example.com

Bare URLs are auto-linked in GitHub Flavored Markdown. For standards compliance, wrap URLs in angle brackets (<url>). The angle-bracket form works in all Markdown flavors. Auto-linking can be disabled in some parsers.

https://example.com

<https://example.com>

<http://www.google.com>

Auto-linking bare URLs is supported
in GFM: visit https://example.com now.

Email addresses in angle brackets become clickable mailto: links. The original Markdown spec supported the <text@domain> form. Some renderers obfuscate email addresses to reduce spam harvesting. Use a contact form for better spam protection on public sites.

<[email protected]>

Contact: <[email protected]>

<John Doe <[email protected]>>

Mailto links work in most renderers.

Link titles appear as tooltips on hover. Use double or single quotes around the title. Titles are optional and purely for UX/SEO hints. They do not replace link text — screen readers may ignore them. Keep titles concise.

[hover for title](https://example.com "Example Site")

[reference with title][a]

[a]: https://example.com "Example Site"

[title with single quotes](https://example.com 'Single')

Heading anchors are auto-generated from heading text (lowercased, spaces to hyphens, punctuation removed) in most parsers. For custom IDs, use HTML <a id="..."> or the {#id} attribute extension (Pandoc/marked). Anchor links are essential for tables of contents.

## Section Heading

[jump to Section](#section-heading)

[back to top](#top)

<a id="custom-id"></a>
[custom anchor](#custom-id)

## Heading {#explicit-id}

Image syntax is like links but prefixed with !. The alt text is required for accessibility — it describes the image for screen readers and shows if the image fails to load. The path can be relative, absolute, or a URL. Title is optional.

![alt text](image.png)

![alt text](https://example.com/img.png)

![alt text](/path/to/image.png "Optional title")

Alt text should be meaningful and concise — describe the image's purpose, not just 'image'. For decorative images, an empty alt (alt='') is acceptable to tell screen readers to skip it. Never use 'image of' or 'picture of' — screen readers already announce it.

![A diagram showing the system architecture](architecture.png)

![Photo: mountain landscape at sunset](mountains.jpg "Sunset over the Alps")

![](decorative-icon.png)

Wrap an image in a link by nesting image syntax inside link syntax: [](url). Common for thumbnails that link to full-size versions, badges that link to CI status, and logos that link to home. Keep alt text describing the destination, not just the image.

[![alt text](thumbnail.png)](https://example.com/full)

[![logo](logo.png "Visit home")](/)

[![badge](https://img.shields.io/build.svg)](https://ci.example.com)

Reference images use the same reference style as links, prefixed with !. Define the image reference once and reuse it. Useful when the same image appears multiple times or to keep image-heavy paragraphs readable.

![alt text][img-ref]

[img-ref]: https://example.com/image.png "Title"

![alt][logo]

[logo]: /assets/logo.png

Standard Markdown has no image sizing syntax — use HTML <img> with width/height attributes. Percentage widths enable responsive sizing. The <figure> + <figcaption> combo provides semantic captions (HTML5). Some extended Markdown (Pandoc) supports {width=300}.

<img src="image.png" width="300" height="200" alt="sized image">

<img src="banner.png" width="100%" alt="responsive">

<figure>
  <img src="diagram.png" alt="flowchart">
  <figcaption>Figure 1: System flow</figcaption>
</figure>

Wrap inline code in single backticks. To show backticks inside code, use double backticks as the delimiter (or more). Inline code renders in monospace and is not parsed as Markdown. Great for filenames, commands, and code identifiers.

Use the `printf()` function.

Inline code: `const x = 42;`

Code with backticks: ``use `code` here``

A `<div>` element.

To include a backtick inside a code span, use more backticks as the delimiter than appear inside: double backticks around a single backtick. Outside code spans, escape a backtick with a backslash. The closing fence must match the opening length.

To show a backtick inside code,
use more backticks as delimiters:

`` ` ``        one backtick
`` a`b ``      backtick inside text

Use \ to escape outside code:
A literal backtick: \`

Code spans preserve internal whitespace exactly. A common trick: wrap content with a single leading/trailing space to display leading/trailing spaces that would otherwise be trimmed. One space on each side is stripped automatically.

`  spaced  `  (spaces preserved)

` code ` with one space pad

`function f() { return; }`

`  multi   word   code  `

Backslash escapes special Markdown characters: backtick, asterisk, underscore, curly braces, square brackets, parentheses, hash, plus, minus, dot, exclamation, and the backslash itself. Escaping renders the character literally. Only escape characters that would otherwise be interpreted as formatting.

\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an image

These are the escapable characters in Markdown. Not all need escaping everywhere — # only matters at line start, - in list context, and so on. When in doubt, escape. Curly braces and parentheses usually only need escaping in specific contexts (links, template strings).

\\     backslash
\`     backtick
\*     asterisk
\_     underscore
\{ \}  curly braces
\[ \]  square brackets
\( \)  parentheses
\#     hash
\+     plus
\-     minus
\.     dot
\!     exclamation

Indenting by 4 spaces (or a tab) creates a code block. Indented code blocks lack syntax highlighting and a language tag. They cannot be used inside list items (treated as continuation). Prefer fenced code blocks for new content — indented blocks are legacy.

Normal paragraph.

    // indented code (4 spaces)
    function hello() {
      console.log("hi");
    }

Back to normal text.

Triple backticks or triple tildes create fenced code blocks. Fences are preferred over indented blocks — they are unambiguous and support language hints. Tildes (~~~) are useful when the code itself contains triple backticks. Always close the fence with the same character count.

```
plain code block
multiple lines
```

~~~
also a fenced block
using tildes
~~~

Add a language identifier right after the opening fence for syntax highlighting (e.g. js, python). Most renderers use highlight.js or Prism. Common aliases: js, ts, py, rb, sh, json, html, css. If the language is unknown, omit it for plain monospace.

```javascript
const greet = (name) => {
  console.log(`Hello, ${name}!`);
};
```

```python
def greet(name):
    print(f"Hello, {name}!")
```

```bash
echo "Hello, $USER"
```

To display backticks inside a code block, use a different fence (tildes for backtick content, or more backticks than appear inside). Four backticks fence content containing triple backticks. The closing fence must match the opening length.

Use four backticks to wrap triple backticks:

````
```js
console.log("inside");
```
````

Or use tildes to wrap backtick content:

~~~
```js
code with backticks
```
~~~

Fenced code blocks inside list items must be indented to align with the list text (typically 3 spaces for - lists, 4 for 1. lists). Indented code blocks inside lists need 8 spaces (4 for the list + 4 for code). Getting alignment right is one of the trickier Markdown tasks.

1. Item with code:

   ```
   code block indented to align
   ```

2. Next item with inline `code`.

- Or indent code 4 spaces beyond
      the list marker (8 total).

The > character starts a blockquote. You can prefix every line or just the first — most parsers join consecutive lines. Blockquotes render as indented, styled quotes (<blockquote>). Use them for quotations, callouts, and highlighting excerpts.

> This is a blockquote.
> It can span multiple lines.

> Or just prefix the first line
and continuation lines without >
will still be part of the quote.

Use blank > lines to separate paragraphs within a blockquote (otherwise they merge). The > on a blank line keeps the quote open. Without blank lines between paragraphs, the text flows as one paragraph. Always close with a normal line.

> First paragraph of quote.
>
> Second paragraph of quote.
>
> > Nested quote starts here.
> > Continues on next line.

End of quote.

Multiple > characters create nested blockquotes (>> for two levels, >>> for three). Add spaces for readability. Deep nesting (3+ levels) becomes hard to read and style — prefer flattening. Each level adds indentation in HTML output.

> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer

> Outer
>> Deeper
>>> Deepest level

Blockquotes can contain most Markdown elements: headings, lists, code, emphasis, even tables. Prefix each line with > (and a space) to keep them inside the quote. This makes blockquotes powerful for callouts, but complex content requires careful > alignment.

> ## Heading in quote
>
> - list item one
> - list item two
>
> *italic* and **bold** work too.
>
> ```
> code block inside quote
> ```

Markdown has no formal citation syntax. Common conventions: prefix the author with an em dash on a new line, or use HTML <blockquote> with <footer> and <cite> for semantic citations. For academic quotes, consider a footnote with the source.

> Be the change you wish to see
> in the world.

> — Mahatma Gandhi

> "Simplicity is the soul of efficiency."
> — Austin Freeman

<blockquote>
  <p>Quote text.</p>
  <footer>— <cite>Author</cite></footer>
</blockquote>

Tables use pipes (|) to separate columns and hyphens to separate the header. The header row is required. Pipes at line edges are optional but improve readability. Column widths do not matter — cells resize. Tables are a GitHub Flavored Markdown extension.

| Name  | Age | City     |
|-------|-----|----------|
| Alice | 30  | NYC      |
| Bob   | 25  | London   |
| Carol | 35  | Paris    |

Colons in the separator row control alignment: :--- left, :---: center, ---: right. Without colons, default is left. Alignment applies to the whole column and sets the text-align CSS in HTML output. Useful for numeric columns (right-aligned) and headers (centered).

| Left   | Center | Right  |
|:-------|:------:|-------:|
| left   | center | right  |
| L      | C      | R      |

| Default | alignment |
|---------|-----------|
| no mark | left      |

Cells can contain inline Markdown: bold, italic, code, links, strikethrough, emoji. Block elements (headings, lists, code blocks) do not work inside cells — use HTML if needed. Keep cell content short for readability. Escape pipes with a backslash to show literal pipes.

| Feature    | Status | Notes              |
|------------|:------:|--------------------|
| **Bold**   | done   | *finished*         |
| `code`     | wip    | [docs](docs.md)    |
| ~~old~~    | removed| gone in v2         |
| [link][1]  | done   | see [ref][1]       |

Tables scale to many rows and columns but stay simple per cell. For code spans with commas, wrap in backticks. Escape literal pipes with a backslash and pipe. Complex data (multi-line cells, nested tables) requires HTML <table>. Consider a list if the table gets too wide.

| Name  | Role    | Skills              | Available |
|-------|---------|---------------------|:---------:|
| Alice | Lead    | `js`, `ts`, `go`   | yes       |
| Bob   | Junior  | `py`, `sql`         | no        |
| Carol | Senior  | `rust`, `c++`       | yes       |

Escaped pipe: \| literal

Markdown tables are limited: no cell merging, no multi-line content, no block elements, no nested tables. For these, use raw HTML. Keep tables small and scannable. If a table needs footnotes or long text, split it. Tools like TablesGenerator.com help build them quickly.

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

Tip: Use \| to escape pipes.

Limitation: no multi-line cells,
no blockquotes, no lists in cells.

For complex tables, use HTML:
<table><tr><td>cell</td></tr></table>

Footnotes use [^id] markers in text and [^id]: definition elsewhere. The id can be a number or a word. Renderers create clickable superscript numbers and a footnotes section at the bottom. Supported by GFM, Pandoc, and most modern parsers.

Here is a sentence with a footnote.[^1]

[^1]: This is the footnote text.

Another sentence.[^note]

[^note]: Footnotes can use named labels.

A footnote can be referenced multiple times — each [^id] links to the same definition. Continuation lines of the footnote definition are indented. The first reference typically gets the superscript number; subsequent ones link to the same note.

Use the term[^term] twice[^term] in the text.

[^term]: A single definition referenced
    multiple times.

First[^1] and second[^1] reference.

[^1]: One definition, two links back.

Inline footnotes (^[text]) embed the note content directly at the reference, supported by Pandoc and some extensions (not GFM core). They keep everything in one place but can interrupt reading flow. Use them for short notes; long ones are better as references.

Here is an inline footnote^[The note text
right here in the body.] in a sentence.

Pandoc also supports: ^[inline notes].

And another[^1].

[^1]: Traditional reference style.

Footnote definitions can be placed anywhere in the document — renderers collect and display them at the end. Indent continuation lines (4 spaces). Footnotes work inside blockquotes and list items. The position in source does not affect output position.

Body text with a note.[^1]

More paragraphs here.

[^1]: Definitions can appear anywhere.
    They float to the bottom in output.

> Even inside blockquotes.[^2]

[^2]: The renderer collects all notes
    and renders them at the end.

Footnote definitions support inline Markdown (bold, italic, code) and multi-paragraph content (indent continuation lines by 4 spaces). Indented code blocks inside footnotes need 8 spaces. Keep footnotes concise — long technical content is better in the main text or an appendix.

See the API[^api] for details.

[^api]: Use `fetch('/api/data')` to call.
    Supports **bold** and *italic*.
    Multi-paragraph: indent each line.

    Code blocks need indentation:
        indented code inside footnote

Definition lists use a term on one line, then a colon (:) followed by the definition. Supported by PHP Markdown Extra, Pandoc, and some extensions (not GFM core). Renders as <dl><dt><dd>. Useful for glossaries and term-definition pairs.

Term
: Definition of the term.

Markdown
: A lightweight markup language.

HTML
: HyperText Markup Language.

Multiple consecutive terms (without colons) can share a single definition. Each term becomes a <dt>, the definition a <dd>. Useful when the same concept has multiple names or aliases. Keep terms on separate lines.

CSS
Cascading Style Sheets
: A style sheet language.

JS
JavaScript
: A programming language.

Both terms
: Share one definition.

Multiple consecutive definitions (each starting with a colon) for one term create multiple <dd> elements. Useful for listing several distinct meanings or aspects of a term. Each colon-line is a separate definition entry.

Markdown
: A markup language.
: A tool for writing for the web.

Apple
: A fruit.
: A technology company.

Nested definition lists require indenting the inner list (2-4 spaces) within the outer definition. Parser support varies — not all renderers handle nesting. For complex hierarchical term structures, consider HTML <dl> for reliability. Test in your target renderer.

Term
: Definition one.

  Nested term
  : Nested definition.

: Definition two for top term.

Definition list entries can contain multiple paragraphs, blockquotes, and code blocks — indent continuation content by 4 spaces (beyond the colon). Code blocks inside need 8 spaces total. This is powerful but fragile; complex content is safer in HTML <dl>.

Markdown
:   A markup language.

    With multiple paragraphs in the
    definition (indent 4 spaces).

    > Blockquote inside definition.

:   Second definition with code:

        indented code (8 spaces)

Most parsers do not auto-generate TOCs by default. Some (marked with the toc plugin, MDX) support [TOC] or {:toc} placeholders. Tools like Doctoc and markdown-toc generate them from headings. For static sites, TOC components read heading anchors at build or runtime.

## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Usage](#usage)
4. [FAQ](#faq)

Some parsers auto-generate a TOC
with `[TOC]` or `{:toc}` markers.

A manual TOC is a nested list of links to heading anchors. Anchor ids are derived from heading text (lowercase, hyphens for spaces, punctuation removed). Indent to reflect heading hierarchy. Update manually when headings change, or use a generator.

# My Document

## Contents
- [Intro](#intro)
- [Setup](#setup)
  - [Prerequisites](#prerequisites)
  - [Install](#install)
- [Usage](#usage)

## Intro
...

Anchor generation varies by parser. Common rules: lowercase, spaces to hyphens, strip punctuation, keep alphanumerics. GitHub keeps emoji and some unicode. Numbers and dots are often removed. When unsure, inspect the rendered HTML to find the actual id.

## Hello World        -> #hello-world
## Hello, World!      -> #hello-world
## C++ & Rust         -> #c--rust
## Uber Heading       -> #uber-heading
## 1. Getting Started  -> #1-getting-started
## API v2.0           -> #api-v20

For reliable anchors, add explicit IDs. The {#id} attribute syntax works in Pandoc, marked, and some extensions. The HTML <a id="..."> trick works everywhere — place it before or inside the heading. Custom IDs survive heading text changes.

## Heading {#custom-id}

<a id="my-anchor"></a>
## Heading

## Heading<a id="also"></a>

[link to custom](#custom-id)

Back-to-top links improve navigation in long documents. The <details>/<summary> HTML creates a collapsible TOC — great for sidebars or long READMEs. Combine with anchor links for smooth navigation. Add scroll-margin-top in CSS to offset fixed headers.

## Section

Content here.

[Back to top](#table-of-contents)

---

<details>
<summary>Table of Contents</summary>

- [Section 1](#section-1)
- [Section 2](#section-2)
</details>

Emoji shortcodes (:name:) are supported by GitHub/GitLab (using the EmojiOne/Twemoji set). There are thousands of named emoji. Shortcodes are convenient but not portable — they may render literally in non-GFM parsers. Use raw Unicode emoji for maximum compatibility.

:smile: :heart: :thumbsup: :rocket:

GFM supports shortcodes:
:sparkles: new feature :tada:

:checkered_flag: launch!
:bug: fixed issue #42

Most modern editors and renderers handle raw Unicode emoji directly — just paste them. Shortcodes are GitHub-specific. Emoji can convey tone and status (check/cross for results, bug for bugs). Use them sparingly in formal docs; they are great in READMEs and changelogs.

:smile: smile    :heart: heart    :thumbsup: thumbsup
:rocket: rocket   :star: star     :warning: warning
:check: check    :x: cross       :bulb: bulb
:fire: fire      :tada: tada      :bug: bug
:book: book      :wrench: wrench  :zap: zap

HTML entities work in Markdown since it passes through to HTML. Use &amp; for literal ampersands (especially in URLs/attributes), &lt; &gt; for angle brackets, &copy; &reg; &trade; for symbols. Numeric forms (&#169;) and hex (&#x00A9;) cover any Unicode character.

&  <  >  "  '

©  ®  ™

— – …

©  ©

Use & to show a literal &.

Markdown does not convert plain punctuation to typographic characters (smart quotes) by default — use HTML entities or paste Unicode. Em dashes and curly quotes improve typography. Many editors auto-correct these. For arrows and symbols, entities are clearest.

-- em dash (or —)
-- en dash (or –)
... ellipsis (or …)
' ' curly quotes (‘ ’)
" " curly quotes (“ ”)
-> arrow (or →)
(tm) (r) (c)

Emoji combine with all Markdown elements: headings, lists, bold, links, blockquotes. They add visual cues to changelogs, READMEs, and issue templates. Keep emoji usage consistent (for example, keep a changelog convention). Avoid emoji in formal/academic writing.

## New Features

- :sparkles: Added dark mode
- :bug: Fixed login bug
- :memo: Updated docs

**Status:** :white_check_mark: Ready

> :warning: **Warning:** Deprecated!

[:book: Read the docs](/docs)

Mermaid is a text-based diagramming language rendered by GitHub, GitLab, and many static site generators. Wrap Mermaid code in a mermaid fenced block. flowchart TD (top-down) or LR (left-right) defines direction. Nodes use [], {}, () for different shapes.

```mermaid
flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[Do it]
    B -->|No| D[Do not]
    C --> E[End]
    D --> E
```

Sequence diagrams show interactions between participants over time. ->> is a solid arrow (request), -->> is a dashed arrow (response). participant declares actors. Useful for documenting API flows, protocols, and message passing. Auto-rendered on GitHub.

```mermaid
sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B-->>A: Hi Alice!
    A->>B: How are you?
    B-->>A: Good, thanks!
```

Class diagrams model object-oriented structures. + means public, - private, # protected. <|-- denotes inheritance. Mermaid supports associations, compositions, and interfaces. Great for documenting code architecture directly in Markdown.

```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +fetch() void
    }
    Animal <|-- Dog
```

State diagrams show state transitions. [*] marks start/end states. Arrows label transitions with events (state --> state: event). Useful for documenting protocols, UI states, and lifecycle of objects. stateDiagram-v2 is the modern syntax.

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Done: complete
    Processing --> Error: fail
    Done --> [*]
    Error --> [*]
```

Gantt charts visualize project schedules. dateFormat sets date parsing. Tasks use id, start, duration (e.g. 7d). 'after a1' chains tasks. Sections group related tasks. Useful for READMEs and project plans — auto-rendered on GitHub without external tools.

```mermaid
gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Design
    Spec        :a1, 2024-01-01, 7d
    Mockups     :after a1, 5d
    section Build
    Develop     :2024-01-13, 14d
    Test        :7d
```

Pie charts show proportions as percentages (values are relative). The title is optional. Labels in quotes, values after colons. Mermaid also supports git graphs, ER diagrams, journey maps, and mind maps — all renderable in Markdown on supported platforms.

```mermaid
pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 18
    "Edge" : 5
    "Firefox" : 3
    "Other" : 9
```

GitHub Flavored Markdown (GFM) task lists render interactive checkboxes on GitHub. [x] is checked, [ ] unchecked. They work in issues, PRs, comments, and READMEs. Progress bars appear in issue lists. The syntax is now widely supported beyond GitHub.

- [x] Done task
- [ ] Todo task
- [ ] Another todo

## Project Status
- [x] Design
- [x] Implement
- [ ] Test
- [ ] Deploy

GFM adds strikethrough (~~text~~) to standard Markdown. It works across lines and combines with other formatting. Renders as <del>. Originally a GFM extension, now in the CommonMark spec additions. Useful for showing edits and deprecations.

~~deleted text~~

old ~~price~~ new

~~this line is wrong~~

Combine: **bold ~~struck~~ text**

~~multi-line
strikethrough~~

Tables are a GFM feature (not original Markdown). The pipe syntax with a header row and separator is required. GFM tables support alignment, inline formatting, and escaped pipes. For complex tables (merging, nesting), fall back to HTML.

| Feature    | Status |
|------------|:------:|
| Tables     | yes    |
| Tasks      | yes    |
| Auto-links | yes    |

Tables are core to GFM, not in
the original Markdown spec.

GitHub Alerts (2023+) use a [!TYPE] marker on the first line of a blockquote: NOTE, TIP, IMPORTANT, WARNING, CAUTION. They render with distinct colors and icons on GitHub. Great for callouts in READMEs and docs. The syntax is GitHub-specific.

> [!NOTE]
> Useful information that users
> should know.

> [!WARNING]
> Urgent info about risks.

> [!IMPORTANT]
> Key information.

> [!TIP]
> Helpful advice.

GFM filters raw HTML for safety — <script>, <style>, <title>, sometimes <iframe>, and event handlers are stripped. This prevents XSS in user-generated content. Safe HTML like <details>, <kbd>, <sup> passes through. Know your renderer's allow-list when mixing HTML.

GFM sanitizes some HTML tags:

<script>alert('xss')</script>
<style>body { color: red; }</style>
<title>Page</title>

These are stripped for security.

GFM auto-links bare URLs (https://...) and www. domains without angle brackets. For portability, angle brackets (<url>) work in all flavors. Auto-linking can be surprising — use angle brackets when you want to display a URL literally with other text adjacent.

Visit https://example.com now.

www.google.com auto-links too.

<https://example.com> always works.

In GFM, bare URLs and www. links
become clickable automatically.

The ==text== highlight syntax is an extension (not in GFM or CommonMark) — supported by some parsers like Markdown-it with a plugin. The HTML <mark> tag is universally supported. Use highlighting to emphasize key terms; overuse reduces impact.

==highlighted text==

<mark>HTML highlight</mark>

Some parsers (not GFM core) support
==this syntax== for highlighting.

Use <mark> for universal support.

Subscript (~text~) and superscript (^text^) are Pandoc/markdown-it extensions, not standard. For universal rendering, use HTML <sub>/<sup> or Unicode. Useful in scientific and mathematical content written in Markdown.

H~2~O (subscript)

x^2^ (superscript)

E = mc^2^

H~2~SO~4~

Pandoc/R Markdown support ~ and ^.

The {#id .class key=val} attribute syntax (Pandoc, some markdown-it plugins) attaches HTML attributes to elements. Useful for styling hooks, custom anchors, and link targets. Not portable — falls back to literal text in unsupported parsers. Use sparingly.

## Heading {#id .class}

![alt](img.png){width=50%}

[link](url){target=_blank}

> Quote {.callout}

Custom containers (:::type ... ::: ) are supported by VuePress, Docusaurus, VitePress and similar docs tools. They render as styled callout boxes. The type maps to a CSS class. Great for themed docs but not portable to plain Markdown renderers.

:::note
This is a note container.
:::

:::warning
This is a warning.
:::

::: details Open me
Hidden content.
:::

Math support depends on the renderer: GitHub supports $...$ inline and $$...$$ block (with MathJax/KaTeX). Not all Markdown parsers support math. For maximum compatibility, render math to images or use MathJax directly. Useful for scientific and technical docs.

Inline: $E = mc^2$ in a sentence.

Block:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Some parsers support \( \) and
\[ \] delimiters too.

VS Code has built-in Markdown preview and a rich extension ecosystem. Markdown All in One adds shortcuts (bold, TOC, preview). markdownlint enforces style. Preview Enhanced supports diagrams, math, and exports. Configure word wrap for comfortable editing.

# VS Code Markdown extensions:
- Markdown All in One
- Markdown Preview Enhanced
- markdownlint
- Pandoc

# Built-in preview: Ctrl+Shift+V
# Side-by-side: Ctrl+K V

# Settings:
"[markdown]": {
  "editor.wordWrap": "on",
  "editor.quickSuggestions": true
}

Typora is a popular WYSIWYG Markdown editor — it renders inline as you type, eliminating the split-pane workflow. It supports GFM, tables, code fences, math, and Mermaid. Exports to many formats via built-in tools. Paid but polished; great for writing-focused workflows.

Typora: a WYSIWYG Markdown editor.

- Live rendering as you type
- No split pane (instant preview)
- Supports tables, diagrams, math
- Export to PDF, HTML, Word, LaTeX
- Themes and custom CSS

Shortcuts:
- Ctrl+/ toggle source code mode
- Ctrl+B bold, Ctrl+I italic

Obsidian stores notes as local Markdown files with powerful features: wiki-links, backlinks, a graph view, and tags. It extends Markdown with callouts, embeds, and Dataview. Ideal for Zettelkasten and personal knowledge management. Free for personal use.

Obsidian: a Markdown knowledge base.

- Plain-text .md files (local-first)
- Bidirectional [[wiki links]]
- #tags and nested tags
- Backlinks and graph view
- Plugins for almost everything
- Callouts: > [!note] Title

[[note|alias]] for renamed links.

markdownlint enforces consistent style across Markdown files. Configure rules in .markdownlint.json. Common disables: MD013 (line length) for prose, MD033 (inline HTML) when HTML is needed. MD040 reminds you to tag code fences with a language. Integrates with CI and editors.

# .markdownlint.json (config)

{
  "MD013": false,
  "MD024": { "siblings_only": true },
  "MD033": false,
  "default": true
}

# Rules (examples):
# MD013 line length
# MD024 no duplicate headings
# MD033 no inline HTML
# MD040 fenced code needs language

Pandoc is the 'Swiss army knife' of document conversion — Markdown to/from HTML, PDF, Word, LaTeX, EPUB, slides. It supports Markdown extensions (citations, math, definition lists, raw attributes). The -s flag creates standalone documents. Indispensable for academic and publishing workflows.

# Convert Markdown to many formats:

pandoc input.md -o output.html
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o slides.pdf

# Markdown to a self-contained HTML:
pandoc input.md -s -o output.html

# With a table of contents:
pandoc input.md --toc -o output.html

# Support extensions:
pandoc -f markdown+smart input.md

Online editors are great for quick edits and sharing. StackEdit and Dillinger are full-featured solo editors. HackMD/HedgeDoc add real-time collaboration. GitHub's web editor has a Preview tab. All support standard Markdown; GFM features work best on GitHub's editor.

Popular online Markdown editors:

- StackEdit (stackedit.io)
  Full-featured, syncs to cloud.

- Dillinger (dillinger.io)
  Clean, exports to many formats.

- HackMD / HedgeDoc
  Real-time collaborative editing.

- GitHub web editor
  Preview tab for .md files.

- Markdown Live Preview
  Lightweight, instant preview.

Markdown's core principle is readability as plain text. Prefer the most readable syntax: # headings, - lists, **bold**. Avoid over-nesting and excessive formatting. If the raw source is pleasant to read in a text editor, you are using Markdown well.

# Good: readable as plain text
## Section
Use **bold** for emphasis, not
__bold__ (asterisks are clearer).

# Bad: hard to read raw
##Section or ***overkill***

Tip: Preview raw Markdown often.
If it reads well as text, it is good.

Two valid approaches: hard-wrap (one sentence per line) gives clean git diffs and easy editing; soft-wrap (one paragraph per line) avoids reflow work. Pick one per project and stay consistent. Configure your editor's wrap width (typically 80-120 chars) accordingly.

# Hard wrap (one sentence per line):
This is sentence one.
This is sentence two.

# Soft wrap (paragraph as one line):
This is a long paragraph that
continues on without hard breaks,
relying on editor wrapping.

# Many projects prefer one sentence
# per line for clean git diffs.

Markdown offers multiple syntaxes for the same result (bold ** vs __, lists - vs * vs +). Pick one convention per project and enforce it with markdownlint. Consistency reduces cognitive load for readers and contributors, and makes automated processing easier.

# Pick one style and stick to it:

- Use - for lists (not * or +)
- Use ** for bold (not __)
- Use * for italic (not _)
- Use ``` for fences (not ~~~)
- Use # for headings (not ===/--)

Consistent style is more
maintainable and professional.

Use reference links for long URLs to keep prose readable. Use inline links for short, local references. Descriptive link text improves accessibility and SEO — avoid 'click here'. Titles add context as tooltips. Group reference definitions at the section or document end.

# Reference links for long URLs:
See the [docs][docs] for details.

[docs]: https://example.com/very/long/url

# Inline for short links:
Edit [index.js](index.js).

# Title for context:
[API](api.md "REST API reference")

Keep link text descriptive,
not 'click here' or 'link'.

Accessibility matters in Markdown: meaningful alt text for images (empty alt for decorative ones), descriptive link text (not 'click here'), proper heading hierarchy (do not skip levels), and semantic HTML (kbd, abbr, cite) where Markdown falls short. Screen readers depend on these.

# Always add alt text to images:
![Diagram of the system](diagram.png)

# Empty alt for decorative images:
![](spacer.png)

# Descriptive link text:
[Read the installation guide](install.md)

# Avoid: [click here](url)
# Use heading hierarchy in order.

# Use semantic HTML when needed:
<kbd>Ctrl</kbd> + <kbd>C</kbd>

Common pitfalls: missing blank lines around block elements (lists, quotes, code), inconsistent indentation in nested lists, unclosed code fences, and mixing tabs/spaces. Always preview before publishing. Run markdownlint to catch issues automatically. Test in your target renderer.

# Missing blank line before lists:
Text
- item  # may merge with text!

# Fix:
Text

- item

# Unclosed code fence:
```
code
# (missing closing fence)

# Inconsistent list indentation:
- a
  - b (2 spaces)
   - c (3 spaces — may break)