Markdown | Basics Cheat Sheet

A simple English guide to Markdown basics. Learn the essentials you need to get started.

📚 Advanced Guide → - Tables, HTML, Accessibility, and more

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)

*italic* or _italic_
**bold** or __bold__
***bold and italic*** or ___bold and italic___
~~strikethrough~~

Practical Examples

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

💡 Tip: Bold is more visible than italic in most contexts

Lists (Bullet Points, Numbered) and Nesting

Bullet Point Lists

- Item 1
- Item 2
  - Nested item (2-4 spaces indent)
  - Nested item

Numbered Lists

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

Mixed Lists

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

💡 Tip: Always include blank lines before and after lists

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}!")
```

Common Language Identifiers

• JavaScript: js
• Python: py
• HTML: html
• CSS: css
• Shell: bash
• JSON: json

💡 Tip: Specifying the language enables syntax highlighting

Links

Basic Format

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

Internal Links (Jump to Headings)

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

Practical Examples

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

Images

Basic Format

![Alt text](https://example.com/image.jpg)
![Alt text](./local-image.png)

Practical Examples

![Admin panel screenshot](./screenshots/admin-panel.png)
![System architecture diagram](./diagrams/architecture.svg)

💡 Tip: Always include descriptive alt text for accessibility

Horizontal Rules

---

💡 Tip: Blank lines before and after are required

Escaping (Disabling Formatting)

To display Markdown symbols as literal characters, add a backslash \ before them.

\* asterisk → *
\# hash → #
\[ \] brackets → [ ]

Next Steps

Once you’ve mastered the basics, learn more advanced features in the Advanced Guide.

📚 Advanced Guide →

Advanced topics include:

• Blockquotes & Task Lists
• Tables
• Text Color Styling
• HTML Integration Techniques
• Accessibility and SEO Best Practices
• Reference Links

References

• CommonMark Spec - Markdown standard specification
• GitHub Flavored Markdown - GitHub extended specification
• Markdown Guide - Comprehensive guide

Last updated: October 1, 2025