Skip to content

Markdown Guide

This comprehensive guide will help you master Markdown syntax for creating well-formatted documentation. Each section includes both the Markdown syntax and its rendered output.

Basic Syntax

1. Headings

Markdown provides six levels of headings, using # symbols:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

The rendered output looks like this:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

2. Text Formatting

Bold Text

**Bold text** or __Bold text__
Bold text or Bold text

Italic Text

*Italic text* or _Italic text_
Italic text or Italic text

Bold and Italic

***Bold and italic*** or ___Bold and italic___
Bold and italic or Bold and italic

Strikethrough

~~Strikethrough text~~
~~Strikethrough text~~

3. Lists

Unordered Lists

- First item
- Second item
    - Indented item
    - Another indented item
- Third item
  • First item
  • Second item
    • Indented item
    • Another indented item
  • Third item

Ordered Lists

1. First item
2. Second item
    1. Indented item
    2. Another indented item
3. Third item
  1. First item
  2. Second item
    1. Indented item
    2. Another indented item
  3. Third item

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

[GitHub](https://github.com "GitHub's Homepage")
GitHub

[GitHub][1]
[DevOps][2]

[1]: https://github.com
[2]: https://en.wikipedia.org/wiki/DevOps

GitHub DevOps

5. Images

Basic Image

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

Image with Title

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

6. Code

Inline Code

Use `git status` to list all changed files.
Use git status to list all changed files.

Code Blocks

```python
def hello_world():
    print("Hello, World!")
```

def hello_world():
    print("Hello, World!")

Syntax Highlighting

```javascript
function greet(name) {
    console.log(`Hello, ${name}!`);
}
```

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

7. Tables

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:-------------:|-------------:|
| Content      | Content       | Content      |
| Left         | Center        | Right        |
Left-aligned Center-aligned Right-aligned
Content Content Content
Left Center Right

8. Blockquotes

Simple Blockquote

> This is a blockquote

This is a blockquote

Nested Blockquotes

> First level
>> Second level
>>> Third level

First level

Second level

Third level

9. Task Lists

- [x] Completed task
- [ ] Incomplete task
    - [x] Completed subtask
    - [ ] Incomplete subtask
  • [x] Completed task
  • [ ] Incomplete task
    • [x] Completed subtask
    • [ ] Incomplete subtask

10. Horizontal Rules

Any of these will create a horizontal rule: 

---
***
___

11. Escaping Characters

Use backslash to escape special characters: 

\* Not italic \*
\` Not code \`
\[ Not a link \]

* Not italic * ` Not code ` [ Not a link ]

12. Extended Syntax (with Material for MkDocs)

Highlighting Text

==Highlighted text==
==Highlighted text==

Footnotes

Here's a sentence with a footnote[^1].

[^1]: This is the footnote.

Here's a sentence with a footnote[^1].

[^1]: This is the footnote.

Definition Lists

term
: definition

term : definition

Emoji

:smile: :heart: :thumbsup:
:smile: :heart: :thumbsup:

Best Practices

  1. Consistency: Use consistent formatting throughout your document
  2. Spacing: Add blank lines before and after headings
  3. Headers: Use proper header hierarchy (don't skip levels)
  4. Lists: Keep them simple and nested no more than three levels
  5. Code Blocks: Always specify the language for syntax highlighting
  6. Links: Use descriptive text rather than "click here"
  7. Images: Always include alt text for accessibility

Common Pitfalls to Avoid

  1. Forgetting to add two spaces for line breaks
  2. Incorrect nesting of lists
  3. Missing blank lines before and after lists and code blocks
  4. Improper escaping of special characters
  5. Inconsistent heading hierarchy

Tools and Resources

  1. Markdown Editors:

    • Visual Studio Code with Markdown extensions
    • Typora
    • StackEdit (web-based)

  2. Online Validators:

  3. Cheat Sheets:

Back to top