Markdown Syntax: A Beginner's Guide

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It allows you to write formatted text using a simple, readable syntax that can be converted to HTML and other formats. Today, Markdown is used everywhere from GitHub to Notion, from technical documentation to blog posts.

The beauty of Markdown lies in its simplicity. Unlike HTML or rich text formats, Markdown uses intuitive symbols that are easy to remember and quick to type. This guide will teach you everything you need to know to start writing in Markdown.

Why Learn Markdown?

Before diving into the syntax, let's understand why Markdown is worth learning:

1. Universal Compatibility: Markdown works on virtually every platform and application.
2. Future-Proof: Plain text files will always be readable, unlike proprietary formats.
3. Version Control Friendly: Perfect for Git and other version control systems.
4. Fast to Write: No need to reach for your mouse or navigate formatting menus.
5. Easy to Read: Even the raw source is readable and understandable.

Basic Syntax

Headings

Headings are created using the hash symbol (#). The number of hashes indicates the heading level:

# Heading 1 (largest)

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6 (smallest)

Pro tip: Always put a space after the hash symbols. Some Markdown processors require it.

Paragraphs and Line Breaks

Paragraphs are separated by blank lines:

This is the first paragraph.

This is the second paragraph.

For a line break within a paragraph, end the line with two spaces or use <br>:

This is line one.
This is line two.

Text Formatting

Markdown supports several text formatting options:

**Bold text** or **also bold**
_Italic text_ or _also italic_
**_Bold and italic_** or **_also works_**
~~Strikethrough text~~

Results:

• Bold text
• Italic text
• Bold and italic
• Strikethrough text

Blockquotes

Use the greater-than symbol (>) for blockquotes:

> This is a blockquote.
> It can span multiple lines.
>
> > Nested blockquotes are also possible.

This is a blockquote. It can span multiple lines.

Lists

Unordered Lists

Use -, *, or + followed by a space:

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

Ordered Lists

Use numbers followed by a period:

1. First item
2. Second item
3. Third item
   1. Nested numbered item
   2. Another nested item

Pro tip: You can use 1. for all items, and Markdown will automatically number them correctly.

Task Lists

Many Markdown processors support task lists:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task to do

Links and Images

Links

Create links using square brackets for the text and parentheses for the URL:

[Visit DocFlat](https://www.docflat.com)
[Link with title](https://www.docflat.com "DocFlat Homepage")

For automatic links, use angle brackets:

<https://www.docflat.com>
<contact@docflat.com>

Reference-Style Links

For cleaner documents with many links:

Check out [DocFlat][docflat] for PDF conversion.
Read more on [our blog][blog].

[docflat]: https://www.docflat.com
[blog]: https://www.docflat.com/blog

Images

Images use similar syntax with an exclamation mark prefix:

![Alt text](image-url.jpg)
![Logo](logo.png "Optional title")

Tables

Create tables using pipes (|) and hyphens (-):

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Column Alignment

Use colons to specify alignment:

| Left    | Center  |   Right |
| :------ | :-----: | ------: |
| Aligned | Aligned | Aligned |
| Left    | Center  |   Right |

Left	Center	Right
Aligned	Aligned	Aligned
Left	Center	Right

Code

Inline Code

Use backticks for inline code:

Use the `print()` function in Python.

Code Blocks

Use triple backticks for code blocks. Specify the language for syntax highlighting:

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

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

Fenced Code Blocks

You can also use indentation (4 spaces or 1 tab):

    function example() {
        return true;
    }

Horizontal Rules

Create horizontal rules with three or more hyphens, asterisks, or underscores:

---
---

---

---

Advanced Syntax

Footnotes

Some Markdown processors support footnotes:

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

[^1]: This is the footnote content.

Definition Lists

Term 1
: Definition of term 1

Term 2
: Definition of term 2

Abbreviations

The HTML specification is maintained by the W3C.

_[HTML]: Hypertext Markup Language
_[W3C]: World Wide Web Consortium

Markdown Flavors

Different platforms may support different Markdown features:

• CommonMark: The standardized specification
• GitHub Flavored Markdown (GFM): Adds tables, task lists, and more
• MultiMarkdown: Extended syntax with citations and more
• Markdown Extra: PHP implementation with additional features

Best Practices

1. Be Consistent: Pick one style (e.g., * vs - for lists) and stick with it.

2. Use Blank Lines: Separate different elements with blank lines for clarity.

3. Keep Lines Reasonable: While Markdown doesn't require line breaks, keeping lines under 80-100 characters improves readability.

4. Preview Your Work: Use a Markdown preview tool to check formatting.

5. Use Reference Links: For documents with many links, reference-style links keep the source readable.

6. Escape Special Characters: Use backslash (\) to escape characters like *, _, [, etc.

Common Mistakes to Avoid

1. Forgetting spaces after headings: #Heading won't work; use # Heading.

2. Missing blank lines: Always put blank lines before and after headings, lists, and code blocks.

3. Incorrect nesting: Use consistent indentation (2 or 4 spaces) for nested lists.

4. Unescaped special characters: If you want literal * or _, escape them with \.

Tools and Resources

Online Editors

• Dillinger
• StackEdit
• HackMD

Desktop Applications

• Typora
• Mark Text
• Obsidian

Learning Resources

• CommonMark specification
• GitHub Markdown Guide
• Markdown Tutorial (markdowntutorial.com)

Conclusion

Markdown is an essential skill for anyone working with text content, especially in technical fields. Its simplicity makes it easy to learn, while its flexibility makes it powerful enough for complex documents.

Start with the basics covered in this guide, and gradually incorporate more advanced features as you become comfortable. Before long, you'll be writing Markdown without even thinking about it.

Ready to put your new Markdown knowledge to use? Convert your existing PDF documents to Markdown with DocFlat and start editing them right away!