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:
- Headers
- Emphasis
- Lists
- Unordered Lists
- Ordered Lists
- Task Lists
- Links
- Inline Links
- Reference Links
- Autolinking
- Images
- Code
- Inline Code
- Code Blocks
- Syntax Highlighting
- Tables
- Blockquotes
- Horizontal Rules
- Line Breaks
- Escape Characters
- HTML
- GitHub Specific Features
- Username @mentions
- Issue and Pull Request References
- Commit SHA References
- Emoji
- Automatic Linking for URLs
- Best Practices and Tips
Headers are used to structure your document. There are six levels of headers, marked with # symbols.
Syntax:
# H1
## H2
### H3
#### H4
##### H5
###### H6Example:
# 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 headingRendered Output:
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:
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.
Use unordered lists for items that don't require a specific order.
Syntax:
* Item 1
* Item 2
* Item 3
- Item 1
- Item 2
- Item 3
+ Item 1
+ Item 2
+ Item 3You can use any of the symbols *, -, or + interchangeably.
Example:
* Apples
* Bananas
* OrangesRendered Output:
- Apples
- Bananas
- Oranges
Use ordered lists for items that require a specific sequence.
Syntax:
1. Item 1
2. Item 2
3. Item 3Example:
1. First step
2. Second step
3. Third stepRendered Output:
- First step
- Second step
- Third step
Create interactive checklists within your documents.
Syntax:
- [ ] Incomplete task
- [x] Completed taskExample:
- [ ] Write the introduction
- [x] Finish the research
- [ ] Write the conclusionRendered Output:
- Write the introduction
- Finish the research
- Write the conclusion
Inline links directly embed the URL within the text.
Syntax:
[Link text](URL)Example:
Visit [GitHub](https://github.com).Rendered Output:
Visit GitHub.
Reference links define the URL separately, allowing for cleaner text and easier maintenance.
Syntax:
[Link text][link_label]
[link_label]: URLExample:
This is a link to [Google][google].
[google]: https://www.google.comRendered Output:
This is a link to [Google][google].
URLs and email addresses are automatically converted into links.
Example:
Visit https://www.github.com.
Contact [email protected].Rendered Output:
Visit https://www.github.com. Contact [email protected].
Embed images directly into your documents.
Syntax:
Example:
Rendered Output:
Use inline code to highlight short snippets of code within a sentence.
Syntax:
`code`Example:
The `printf()` function is used to print output.Rendered Output:
The printf() function is used to print output.
Display longer blocks of code with syntax highlighting.
Syntax:
```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")
GitHub automatically detects and highlights the syntax of common programming languages. You can specify the language using the syntax mentioned above for code blocks.
Create tables to organize data in rows and columns.
Syntax:
| 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:
| 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 |
Use blockquotes to quote text from another source.
Syntax:
> This is a blockquote.Example:
> "The only way to do great work is to love what you do." - Steve JobsRendered Output:
"The only way to do great work is to love what you do." - Steve Jobs
Create horizontal lines to visually separate sections.
Syntax:
---
***
___You can use any of the above syntaxes interchangeably.
Example:
---
This is a section below the horizontal rule.Rendered Output:
This is a section below the horizontal rule.
Force line breaks within a paragraph.
Syntax:
Add two spaces at the end of a line.
Example:
This is the first line.
This is the second line.Rendered Output:
This is the first line.
This is the second line.
Use escape characters to display characters that have special meaning in Markdown.
Syntax:
\characterExample:
\* This is not italic.Rendered Output:
* This is not italic.
You can embed raw HTML code within your Markdown documents.
Example:
<p>This is a paragraph written in HTML.</p>Rendered Output:
This is a paragraph written in HTML.
Mention other GitHub users.
Syntax:
@usernameExample:
@9EEDRendered Output:
@octocat
Automatically link to issues and pull requests.
Syntax:
#issue_number
#pull_request_numberExample:
See #123 for more details.
This fixes #456.Automatically link to specific commits.
Syntax:
commit_SHAExample:
This change was introduced in a1b2c3d.Add emoji to your text using shortcodes.
Syntax:
:emoji_shortcode:Example:
:+1: This is great!Rendered Output:
đź‘Ť This is great!
GitHub automatically converts URLs into clickable links.
- 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!