Markdown | Guide & Cheat Sheet

This page is a comprehensive English guide that covers Markdown basics, advanced features, practical considerations, and accessibility support all in one place.

• Audience: People writing Markdown for blogs (WordPress, etc.), GitHub (GFM), technical documentation, documentation sites, and note-taking tools

• Compliance: Based on CommonMark, including GitHub Flavored Markdown (GFM) and extended features from major platforms

• Level: For beginners through advanced users

Basic Writing and Rules

🔑 Important Fundamental Rules

1. Blank lines are required: Use blank lines to separate paragraphs, headings, and lists

2. Single space after symbols: Always add a single space after heading # or list markers

3. Heading hierarchy: # (H1) is for article titles. Use ## and below for body content

4. One sentence per line (recommended): This makes version control easier

5. Character encoding: Use UTF-8 (supports multilingual content)

✅ Good Examples・❌ Bad Examples

✅ Good example:
# Main Title

## Section Heading

This is a paragraph.

- List item 1
- List item 2

❌ Bad example:
#Main Title (no space)
##Section Heading
This is a paragraph. (no blank line)
-List item 1 (no space)

Headings

# Title (H1)
## Heading (H2)
### Subheading (H3)
#### Heading 4 (H4)
##### Heading 5 (H5)
###### Heading 6 (H6)

📝 Practical Notes

• One H1 per article: Recommended for SEO purposes

• Avoid skipping heading levels: Don’t jump from H2 directly to H4

• Don’t use Markdown formatting in headings: Avoid # **Bold Heading**

• Space between language types: Add a single space between Japanese and alphanumeric characters for readability

# Web API Design Guide (recommended)
# WebAPIDesignGuide (not recommended)

Paragraphs and Line Breaks

Basic Rules

• Paragraphs: Separated by blank lines

• In-line line breaks: Two spaces at end of line + Enter

• Hard breaks: Use <br> tag

This is the first paragraph.
This is also part of the first paragraph.

This is the second paragraph.

To break a line within text,
add two spaces at the end like this.

You can also break<br>with HTML tags.

⚠️ Common Issues

❌ Issue: Trailing spaces removed by editor
Solution: Use <br> tag

❌ Issue: Line breaks don't render as expected
Solution: Preview while editing

Emphasis (Bold, Italic) and Strikethrough

*italic* or _italic_
**bold** or __bold__
***bold and italic*** or ___bold and italic___
~~strikethrough~~
<u>underline</u> <!-- Using HTML -->
==highlight== <!-- Supported in some platforms -->

📝 Practical Examples

**Important**: This setting is required.
*Note*: Back up your data before running this.
~~Old version~~ → New version

🎯 Tips for Best Visibility

• Bold is more visible than italic in English text

• Adjust spacing between symbols and text naturally

• Avoid excessive decoration (prioritize readability)

Text Color Changes

Markdown doesn’t have a standard text color feature, but you can achieve it by combining HTML.

Basic Format

<span style="color: red;">Red text</span>
<span style="color: #0066cc;">Blue text (HEX notation)</span>
<span style="color: rgb(255, 128, 0);">Orange (RGB notation)</span>

Common Color Examples

<!-- Basic colors -->
<span style="color: red;">Critical warning</span>
<span style="color: blue;">Link or information</span>
<span style="color: green;">Success message</span>
<span style="color: orange;">Important note</span>
<span style="color: gray;">Supplementary info</span>

<!-- Custom colors (HEX) -->
<span style="color: #ff6b6b;">Bright red</span>
<span style="color: #4ecdc4;">Turquoise</span>
<span style="color: #ffe66d;">Yellow</span>
<span style="color: #a8e6cf;">Light green</span>

Combining with Background Color

<span style="color: white; background-color: red; padding: 2px 6px; border-radius: 3px;">Error</span>
<span style="color: white; background-color: green; padding: 2px 6px; border-radius: 3px;">Success</span>
<span style="color: black; background-color: yellow; padding: 2px 6px;">Warning</span>

Practical Examples

📝 **Note**: <span style="color: #0066cc;">Available in version 2.0 and later</span>. ⚠️ **Warning**:
<span style="color: red; font-weight: bold;">This feature is deprecated</span>

✅ **Complete**: <span style="color: green;">All tests passed successfully</span>

Blockquotes

> Single-level blockquote
>> Two-level blockquote
>>> Three-level blockquote

> You can use **bold** and `code` inside blockquotes
>
> Multi-paragraph blockquotes are also possible

Practical Examples

> "Programs should be written for people to read,
> and only incidentally for machines to execute."
> - Harold Abelson

> ⚠️ **Warning**
> This operation cannot be undone.

Lists (Bullet Points, Numbered) and Nesting

Bullet Point Lists

- Item 1
- Item 2
  - Nested item
  - Nested item
    - Further nested
+ Plus signs also work
* Asterisks also work

Numbered Lists

1. First item
1. Second item (all can be 1.)
   1. Nested numbered item
   1. Nested numbered item
1. Third item

Mixed Lists

1. First do this
   - Things to prepare
   - Important notes
2. Then execute this
   - Step A
   - Step B

📝 Professional Tips

• Use 1. for all items: Makes reordering easier

• Nesting indent: Use 2-4 spaces (adjust per environment)

• Blank lines around lists: Always include them

• Long list items: Keep one item per line

Task Lists (Checkboxes)

- [ ] Incomplete task
- [x] Completed task
- [X] Completed task (capital X works too)
- [ ] Nested task
  - [x] Subtask 1
  - [ ] Subtask 2

Practical Example

## Project Progress

- [x] Requirements
- [x] Design
- [ ] Implementation
  - [x] Frontend
  - [ ] Backend
  - [ ] Testing
- [ ] Deployment

Platform Support

• ✅ GitHub, GitLab

• ✅ Notion, Obsidian

• ❌ Standard Markdown

• ⚠️ WordPress (plugin-dependent)

Code (Inline & Blocks) and Language Specification

Inline Code

Run the command `npm install` to proceed.
Set the variable `userName` to a value.

Code Blocks

```js
// JavaScript example
function greet(name) {
  console.log(`Hello, ${name}!`);
}
```

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

```bash
# Shell command example
npm install
git commit -m "Update README"
```

Common Language Identifiers

Advanced Examples

```js:script.js
// Filename specification (platform-dependent)
console.log("Hello World");
```

```js {1,3-5}
// Line highlighting (platform-dependent)
const a = 1;
const b = 2;
const c = a + b;
const d = c * 2;
console.log(d);
```

⚠️ Important Notes

• Backtick handling: If code contains “use ```` (4 or more) or~~~ instead

• Indentation: Indentation within code blocks is preserved

• Character encoding: Use UTF-8 for comments with special characters

Links

Basic Format

[Link text](https://example.com)
[Link with title](https://example.com "Link description")
<https://example.com> <!-- Auto-link -->

Reference Links

See [references][ref1] or [official site][official] for more info.

[ref1]: https://example.com/ref "Reference Title"
[official]: https://official-site.com

Internal Links

[Back to top](#top)
[Link to heading](#heading-example)
[Image section](#images)

<!-- GitHub: lowercase, spaces→hyphens, symbols removed -->
<!-- Example: "## Heading Example" → "#heading-example" -->

Practical Examples

### Common Link Patterns

- [Official Documentation](https://docs.example.com)
- [GitHub Repository](https://github.com/user/repo)
- [Contact](mailto:contact@example.com)
- [PDF File](./documents/manual.pdf)

Using HTML (New Tab, Download, etc.)

<a href="https://example.com" target="_blank" rel="noopener noreferrer">Open in new tab</a>
<a href="./file.pdf" download>Download PDF</a>

⚠️ Common Issues and Solutions

❌ Issue: Parentheses in URLs not interpreted correctly
[Link](https://example.com/(path))

✅ Solution 1: URL encoding
[Link](https://example.com/%28path%29)

✅ Solution 2: Reference link
[Link][wiki]

[wiki]: https://example.com/(path)

✅ Solution 3: Angle brackets
<https://example.com/(path)>

❌ Issue: Relative paths don't work
✅ Solution: Use absolute paths or platform-specific syntax

Images

Basic Format

![Alt text](https://example.com/image.jpg)
![Alt text](https://example.com/image.jpg "Image description")
![](./local-image.png) <!-- Alt text optional but not recommended -->

Size Specification (Using HTML)

<img src="https://example.com/image.jpg" alt="Description" width="600" height="400">
<img src="./image.png" alt="Description" style="max-width: 100%; height: auto;">

Advanced Examples

<!-- Centered alignment -->
<div align="center">
  <img src="./image.png" alt="Centered image" width="500">
</div>

<!-- With caption -->
<figure>
  <img src="./image.png" alt="Figure 1">
  <figcaption>Figure 1: System Architecture</figcaption>
</figure>

Practical Examples

### Image Usage by Type

<!-- Screenshot -->
![Admin panel screenshot](./screenshots/admin-panel.png)

<!-- Icon -->
![GitHub icon](https://github.com/favicon.ico)

<!-- Diagram -->
![System architecture diagram](./diagrams/system-architecture.svg)

<!-- Badge -->
![Build passing](https://img.shields.io/badge/build-passing-brightgreen)

📝 Accessibility Best Practices

<!-- ✅ Good example -->
![Login screen screenshot showing username and password input fields and login button](./login-screen.png)

<!-- ❌ Bad example -->
![](./login-screen.png)
![Image](./login-screen.png)

⚠️ Common Issues

• Relative paths: Behavior varies by platform

• File size: Large images affect load times

• Format support: New formats like WebP and AVIF need compatibility checks

Tables and Alignment

Basic Table

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

Alignment Specification

| Left     | Center   | Right    |
|:---------|:--------:|----------:|
| Left     | Center   | Right    |
| Data     | Data     | Data     |

Practical Example

### Feature Comparison

| Feature      | Free Plan | Pro Plan | Enterprise |
|:-------------|:---------:|:--------:|:----------:|
| Users        | 5         | 50       | Unlimited  |
| Storage      | 1GB       | 100GB    | 1TB        |
| Support      | ❌        | ✅       | ✅         |
| Price        | Free      | $10/mo   | Contact us |

Complex Tables (Using HTML)

<table>
  <thead>
    <tr>
      <th rowspan="2">Item</th>
      <th colspan="2">2024</th>
    </tr>
    <tr>
      <th>Q1</th>
      <th>Q2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Revenue</td>
      <td>$1M</td>
      <td>$1.2M</td>
    </tr>
  </tbody>
</table>

📝 Table Creation Tips

• Alignment: Use editor formatting features for tables

• Line breaks: Use <br> for breaks within cells

• Escaping: Escape pipe characters with \|

• Readability: Consider screen width when setting column widths

Horizontal Rules

---

***

___

<!-- Blank lines before and after are required -->

Text above

---

Text below

Escaping (Disabling Formatting)

Characters Requiring Escaping

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

Practical Examples

The price is \$100.
The file is named \*README\*.md.
The array is defined as \[1, 2, 3\].

Footnotes

Text with a footnote[^1] or multiple footnotes[^note].

Some sections need detailed explanation[^detail].

[^1]: This is the footnote content.
[^note]: Another footnote. You can use **bold** and [links](https://example.com) here.
[^detail]: Long explanations and multi-paragraph footnotes are also supported.

    Including second paragraphs.

Platform Support

• ✅ GitHub, GitLab

• ✅ Many static site generators

• ❌ WordPress (standard)

• ⚠️ Platform-dependent

Definition Lists

Term 1
: Definition of term 1. Can span multiple lines.
: Multiple definitions are also possible.

Term 2
: Definition of term 2.

HTML
: HyperText Markup Language
: A markup language for creating web pages

CSS
: Cascading Style Sheets
: A language for defining web page styles

Collapsible Content (HTML details/summary)

<details>
  <summary>Click to show details</summary>

  This is the collapsible content.

  - Lists work
  - **Bold text** works
  - `Code` works

```js
console.log("Code blocks work too");

Practical Examples

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

  1. [Introduction](#introduction)
  2. [How to Use](#how-to-use)
  3. [FAQ](#faq)
</details>

<details>
  <summary>⚠️ Important Notes</summary>

  Before executing this operation, verify the following:

  - Backup is taken
  - Permissions are confirmed
  - Dependencies are checked
</details>

HTML Integration Rules

Basic Principles

1. Minimal use: Only when Markdown can’t do it

2. Valid HTML: No unclosed tags

3. Security: Avoid dangerous attributes

4. Blank lines: Required before and after HTML blocks

Safe HTML Tags

<!-- Formatting -->
<u>underline</u>
<del>deleted</del>
<ins>inserted</ins>
<sub>subscript</sub>
<sup>superscript</sup>

<!-- Layout -->
<div align="center">Centered text</div>
<span style="color: red;">Red text</span>

<!-- Media -->
<video controls width="600">
  <source src="movie.mp4" type="video/mp4">
</video>

<audio controls>
  <source src="audio.mp3" type="audio/mpeg">
</audio>

⚠️ Tags to Avoid

❌ JavaScript: onclick, onload, etc.
❌ Dangerous CSS: position: fixed, etc.
❌ External resources: Unexpected scripts
❌ Form elements: Security risks

Accessibility and SEO

🎯 Accessibility Best Practices

Heading Structure

✅ Good example:
# Main Title (H1)
## Section 1 (H2)
### Subsection (H3)
## Section 2 (H2)

❌ Bad example:
# Main Title
### Jump directly to H3 (skipping H2)

Image Alt Text

✅ Good example:
![Chart showing 2024 revenue growth from $1M in January to $1.8M in December](./sales-chart.png)

❌ Bad example:
![Chart](./sales-chart.png)
![](./sales-chart.png)

Link Text

✅ Good example:
[Official Markdown Guide website](https://markdownguide.org)

❌ Bad example:
[Click here](https://markdownguide.org)
[Link](https://markdownguide.org)

📊 SEO Best Practices

1. Heading hierarchy: Maintain logical structure

2. Internal links: Link to related pages appropriately

3. Image optimization: Optimize file size and use descriptive alt text

4. Readability: Use proper paragraph breaks and whitespace

References

📚 Official & Specifications

• CommonMark Spec - Markdown standard specification

• GitHub Flavored Markdown Spec - GitHub extended specification

• Markdown Guide - Comprehensive guide

🛠️ Tools

• Dillinger - Online editor

• StackEdit - Browser editor

• Typora - Desktop editor

• markdownlint - Linter

🎨 Extensions & Plugins

• Mermaid - Diagram creation

• KaTeX - Math formula display

• Prism.js - Syntax highlighting

🌐 Platform-Specific

• GitHub Markdown

• GitLab Markdown

• WordPress Gutenberg

• Notion Help

💡 Final Thoughts

Markdown’s greatest strength is its simplicity and readability. Since rendering isn’t always consistent across platforms, always preview your content and check how it displays.

• Prioritize basics: Favor readability over complex formatting

• Know your platform: Understand what features your platform supports

• Always preview: Don’t skip the preview step

• Keep learning: Continuously learn new and better ways to write

Mastering Markdown will make documentation and information sharing more comfortable and efficient. Use this guide as a reference and enjoy better writing!

Last updated: September 29, 2025