Heading Best Practices ▲

• Do not skip levels (e.g. # → ###) unless you have a reason.
• Leave a blank line before and after headings for reliable parsing.
• Optional: add an explicit anchor with {#custom-id} in some processors (Pandoc, some SSGs).

Paragraphs & Line Breaks ▲

Separate paragraphs with a blank line:

This is the first paragraph.

This is the second paragraph.

Result:

This is the first paragraph.

This is the second paragraph.

For a line break within a paragraph (no new paragraph):

Line one  
Line two

Result:

Line one
Line two

💡 Two trailing spaces before the newline create a <br>. Some viewers also accept a trailing \ or <br> HTML tag.

Text Emphasis ▲

Bold & Italic ▲

**bold text**
*italic text*
***bold and italic***

Result:

bold text
italic text
bold and italic

Strikethrough ▲

GFM (GitHub Flavored Markdown) extension:

~~deleted text~~

Result:

deleted text

⚠️ Not part of original Markdown — supported in GFM, Obsidian, VS Code, and most modern viewers.

Links ▲

Inline Links ▲

[Link text](https://example.com)
[Link with title](https://example.com "Hover title")
[Local file](./document.pdf)
[Absolute local file](file:///C:/path/to/file.md)

Result:

Link text
Link with title
Local file
Absolute local file

Local paths: Use forward slashes (/) in paths, even on Windows. For spaces in filenames, encode with %20 or wrap the URL in < >. Prefer relative paths when possible.

Reference Links ▲

Define the URL separately — useful for repeated links or cleaner prose:

Visit [OpenAI][openai] or [Google][google].

[openai]: https://openai.com
[google]: https://google.com "Search engine"

Result:

Visit OpenAI or Google.

Autolinks ▲

Many parsers auto-link bare URLs and emails:

https://example.com
<https://example.com>
<user@example.com>

Result:

https://example.com
https://example.com
user@example.com

Images ▲

Same syntax as links, with a leading !:

![Alt text](image.png)
![Alt text](image.png "Optional title")
![Remote image](https://example.com/photo.jpg)

Result:

Reference-style images:

![Logo][logo]

[logo]: ./assets/logo.png "Site logo"

Result:

Optional HTML for size control (when HTML is allowed):

<img src="./photo.jpg" alt="Photo" width="300">

Result:

Lists ▲

Unordered Lists ▲

Use -, *, or + (consistent within a list):

- Item one
- Item two
- Item three

Result:

• Item one
• Item two
• Item three

Ordered Lists ▲

1. First item
2. Second item
3. Third item

Result:

1. First item
2. Second item
3. Third item

✅ Numbers auto-increment — 1. for every item is valid and often preferred.

Nested Lists ▲

Indent nested items by 2 or 4 spaces (viewer-dependent; 4 is safest):

- Level 1
  - Level 2
    - Level 3
- Back to level 1

1. Ordered parent
   1. Ordered child
   2. Another child
- Mixed nesting works too

Result:

• Level 1
  • Level 2
    • Level 3
• Back to level 1

1. Ordered parent
   1. Ordered child
   2. Another child

• Mixed nesting works too

Task Lists ▲

GFM checkbox syntax:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Result:

• Completed task
• Incomplete task
• Another task

Blockquotes ▲

Prefix lines with >:

> This is a blockquote.

> Multi-line quotes
> continue with `>` on each line.

> Nested quotes:
>> Second level
>>> Third level

Result:

This is a blockquote.

Multi-line quotes continue with > on each line.

Nested quotes:

Second level

Third level

Combine with other elements:

> **Note:** Important information here.
>
> - Point one
> - Point two

Result:

Note: Important information here.

• Point one
• Point two

Code ▲

Inline Code ▲

Wrap text in single backticks:

Use the `printf()` function.
Use `` `backticks` `` inside code by doubling the outer fence.

Result:

Use the printf() function.
Use backticks inside code by doubling the outer fence.

Fenced Code Blocks ▲

Use triple backticks (or tildes) with an optional language tag for syntax highlighting:

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

Result:

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

Tilde alternative:

~~~javascript
console.log("Hello");
~~~

Result:

console.log("Hello");

Nesting backticks: Use more backticks on the outer fence than the longest sequence inside — e.g. wrap a ``` block in ```` to show fence syntax literally. Alternatively, use ~~~ as the outer delimiter instead of backticks.

Horizontal Rules ▲

Three or more of -, *, or _ on a line by themselves:

---
***
___

Result:

✅ Surround with blank lines for reliable rendering.

Tables ▲

GFM pipe tables:

| Column A | Column B | Column C |
|----------|----------|----------|
| Row 1    | Data     | Data     |
| Row 2    | Data     | Data     |

Result:

Alignment with colons in the separator row:

| Left | Center | Right |
|:-----|:------:|------:|
| A    | B      | C     |

Result:

⚠️ Pipe tables are a GFM extension — not in original Markdown.

Escaping Characters ▲

Use backslash \ before special characters to render them literally:

\*not italic\*
\# not a heading
\[not a link\]

Result:

*not italic*
# not a heading
[not a link]

Common escapable characters: \ ` * _ { } [ ] ( ) # + - . ! |

HTML in Markdown ▲

Most viewers allow inline HTML alongside Markdown:

<br>
<hr>
<span class="general-text">Styled span</span>
<details>
  <summary>Click to expand</summary>
  Hidden content here.
</details>

Result:

⚠️ Support varies by viewer. Markdown inside HTML blocks is often not parsed.

Footnotes ▲

Supported in many extended parsers (Pandoc, Obsidian, some SSGs):

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

[^1]: This is the footnote text at the bottom of the document.

Result:

Here is a statement with a footnote.¹

Inline footnotes (Pandoc):

Here is an inline note.^[This appears as a footnote.]

Result:

Here is an inline note.^[This appears as a footnote.]

Best Practices ▲

• Use one H1 per document as the title.
• Prefer consistent list markers (- for unordered is common).
• Use fenced code blocks with language tags for syntax highlighting.
• Prefer reference links when URLs are long or repeated.
• Use relative paths for local links and images when possible.
• Test in your target viewer — extensions (GFM, footnotes, task lists) vary.
• Keep lines readable; wrapping at ~80–120 chars is optional but helps diffs.