Markdown-guide

KO | EN

gitlite — search

#javascript #typescript #android #linux #docker #java #awesome #cli #kubernetes #awesome-list #pytorch #security #ios #open-source

(★ 15)

a complete github markdown guide with every feature

Markdown-guide Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## The Ultimate Guide to GitHub Markdown: Mastering Every Feature

This guide serves as your comprehensive resource for mastering GitHub Markdown. We'll cover every single feature with detailed explanations and practical examples, ensuring you have everything you need to create beautifully formatted documentation, issues, and pull requests on GitHub.

**Table of Contents:**

1. **Headers**
2. **Emphasis**
3. **Lists**
    * Unordered Lists
    * Ordered Lists
    * Task Lists
4. **Links**
    * Inline Links
    * Reference Links
    * Autolinking
5. **Images**
6. **Code**
    * Inline Code
    * Code Blocks
    * Syntax Highlighting
7. **Tables**
8. **Blockquotes**
9. **Horizontal Rules**
10. **Line Breaks**
11. **Escape Characters**
12. **HTML**
13. **GitHub Specific Features**
    * Username @mentions
    * Issue and Pull Request References
    * Commit SHA References
    * Emoji
    * Automatic Linking for URLs
14. **Best Practices and Tips**

---

### 1. Headers

Headers are used to structure your document. There are six levels of headers, marked with `#` symbols.

**Syntax:**

```markdown
# H1
## H2
### H3
#### H4
##### H5
###### H6
```

**Example:**

```markdown
# This is a level 1 heading
## This is a level 2 heading
### This is a level 3 heading
#### This is a level 4 heading
##### This is a level 5 heading
###### This is a level 6 heading
```

**Rendered Output:**

# This is a level 1 heading
## This is a level 2 heading
### This is a level 3 heading
#### This is a level 4 heading
##### This is a level 5 heading
###### This is a level 6 heading

---

### 2. Emphasis

Use emphasis to highlight words or phrases.

**Syntax:**

* **Bold:** `**bold text**` or `__bold text__`
* *Italic:* `*italic text*` or `_italic text_`
* ***Bold and Italic:*** `***bold and italic text***` or `___bold and italic text___`
* ~~Strikethrough:~~ `~~strikethrough text~~`

**Example:**

```markdown
This is **bold** text.
This is *italic* text.
This is ***bold and italic*** text.
This is ~~strikethrough~~ text.
```

**Rendered Output:**

This is **bold** text.
This is *italic* text.
This is ***bold and italic*** text.
This is ~~strikethrough~~ text.

---

### 3. Lists

#### 3.1 Unordered Lists

Use unordered lists for items that don't require a specific order.

**Syntax:**

```markdown
* Item 1
* Item 2
* Item 3

- Item 1
- Item 2
- Item 3

+ Item 1
+ Item 2
+ Item 3
```

You can use any of the symbols `*`, `-`, or `+` interchangeably.

**Example:**

```markdown
* Apples
* Bananas
* Oranges
```

**Rendered Output:**

* Apples
* Bananas
* Oranges

#### 3.2 Ordered Lists

Use ordered lists for items that require a specific sequence.

**Syntax:**

```markdown
1. Item 1
2. Item 2
3. Item 3
```

**Example:**

```markdown
1. First step
2. Second step
3. Third step
```

**Rendered Output:**

1. First step
2. Second step
3. Third step

#### 3.3 Task Lists

Create interactive checklists within your documents.

**Syntax:**

```markdown
- [ ] Incomplete task
- [x] Completed task
```

**Example:**

```markdown
- [ ] Write the introduction
- [x] Finish the research
- [ ] Write the conclusion
```

**Rendered Output:**

- [ ] Write the introduction
- [x] Finish the research
- [ ] Write the conclusion

---

### 4. Links

#### 4.1 Inline Links

Inline links directly embed the URL within the text.

**Syntax:**

```markdown
[Link text](URL)
```

**Example:**

```markdown
Visit [GitHub](https://github.com).
```

**Rendered Output:**

Visit [GitHub](https://github.com).

#### 4.2 Reference Links

Reference links define the URL separately, allowing for cleaner text and easier maintenance.

**Syntax:**

```markdown
[Link text][link_label]

[link_label]: URL
```

**Example:**

```markdown
This is a link to [Google][google].

[google]: https://www.google.com
```

**Rendered Output:**

This is a link to [Google][google].

#### 4.3 Autolinking

URLs and email addresses are automatically converted into links.

**Example:**

```markdown
Visit https://www.github.com.
Contact support@github.com.
```

**Rendered Output:**

Visit https://www.github.com.
Contact support@github.com.

---

### 5. Images

Embed images directly into your documents.

**Syntax:**

```markdown
![Alt text](https://raw.githubusercontent.com/9EED/Markdown-guide/main/image URL)
```

**Example:**

```markdown
![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)
```

**Rendered Output:**

![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

---

### 6. Code

#### 6.1 Inline Code

Use inline code to highlight short snippets of code within a sentence.

**Syntax:**

```markdown
`code`
```

**Example:**

```markdown
The `printf()` function is used to print output.
```

**Rendered Output:**

The `printf()` function is used to print output.

#### 6.2 Code Blocks

Display longer blocks of code with syntax highlighting.

**Syntax:**

```markdown
```language
code block
```
```

Replace `language` with the specific programming language for syntax highlighting (e.g., `python`, `javascript`, `ruby`).

**Example:**

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

greet("World")
```
```

**Rendered Output:**

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

greet("World")
```

#### 6.3 Syntax Highlighting

GitHub automatically detects and highlights the syntax of common programming languages. You can specify the language using the syntax mentioned above for code blocks.

---

### 7. Tables

Create tables to organize data in rows and columns.

**Syntax:**

```markdown
| Header 1 | Header 2 | Header 3 |
|---|---|---|
| Row 1, Column 1 | Row 1, Column 2 | Row 1, Column 3 |
| Row 2, Column 1 | Row 2, Column 2 | Row 2, Column 3 |
```

You can use `:` for alignment:

* `:---` Left align
* `:---:` Center align
* `---:` Right align

**Example:**

```markdown
| Name | Age | City |
|---|---|---|
| John Doe | 30 | New York |
| Jane Doe | 25 | London |
```

**Rendered Output:**

| Name | Age | City |
|---|---|---|
| John Doe | 30 | New York |
| Jane Doe | 25 | London |

---

### 8. Blockquotes

Use blockquotes to quote text from another source.

**Syntax:**

```markdown
> This is a blockquote.
```

**Example:**

```markdown
> "The only way to do great work is to love what you do." - Steve Jobs
```

**Rendered Output:**

> "The only way to do great work is to love what you do." - Steve Jobs

---

### 9. Horizontal Rules

Create horizontal lines to visually separate sections.

**Syntax:**

```markdown
---
***
___
```

You can use any of the above syntaxes interchangeably.

**Example:**

```markdown
---
This is a section below the horizontal rule.
```

**Rendered Output:**

---
This is a section below the horizontal rule.

---

### 10. Line Breaks

Force line breaks within a paragraph.

**Syntax:**

Add two spaces at the end of a line.

**Example:**

```markdown
This is the first line.  
This is the second line.
```

**Rendered Output:**

This is the first line.  
This is the second line.

---

### 11. Escape Characters

Use escape characters to display characters that have special meaning in Markdown.

**Syntax:**

```markdown
\character
```

**Example:**

```markdown
\* This is not italic.
```

**Rendered Output:**

\* This is not italic.

---

### 12. HTML

You can embed raw HTML code within your Markdown documents.

**Example:**

```markdown
<p>This is a paragraph written in HTML.</p>
```

**Rendered Output:**

<p>This is a paragraph written in HTML.</p>

---

### 13. GitHub Specific Features

#### 13.1 Username @mentions

Mention other GitHub users.

**Syntax:**

```markdown
@username
```

**Example:**

```markdown
@9EED
```

**Rendered Output:**

@octocat

#### 13.2 Issue and Pull Request References

Automatically link to issues and pull requests.

**Syntax:**

```markdown
#issue_number
#pull_request_number
```

**Example:**

```markdown
See #123 for more details.
This fixes #456.
```

#### 13.3 Commit SHA References

Automatically link to specific commits.

**Syntax:**

```markdown
commit_SHA
```

**Example:**

```markdown
This change was introduced in a1b2c3d.
```

#### 13.4 Emoji

Add emoji to your text using shortcodes.

**Syntax:**

```markdown
:emoji_shortcode:
```

**Example:**

```markdown
:+1: This is great!
```

**Rendered Output:**

:+1: This is great!

#### 13.5 Automatic Linking for URLs

GitHub automatically converts URLs into clickable links.

---

### 14. Best Practices and Tips

* **Keep it simple:** Use Markdown features for their intended purpose and avoid over-complicating your formatting.
* **Be consistent:** Maintain a consistent style throughout your documents.
* **Preview your work:** Use the Markdown preview feature to ensure your formatting is correct before committing changes.
* **Use headings effectively:** Structure your documents with clear and concise headings.
* **Write clear and concise text:** Focus on conveying information effectively.

---

This comprehensive guide covers every feature of GitHub Markdown. By mastering these features, you can create beautifully formatted and informative content on GitHub. Remember to practice and experiment with different features to fully understand their capabilities. Happy Markdown-ing!

Markdown-guide

Markdown-guide Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Markdown-guide

Markdown-guide Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README