Markdown Guide — Complete Syntax and Best Practices

Markdown is a lightweight markup language that converts plain text into structured HTML using simple, readable syntax — designed to be written in any editor and published anywhere on the web.

What You’ll Learn

• All Markdown syntax elements from headings to footnotes
• GitHub Flavored Markdown (GFM) extensions
• Best practices for documentation, READMEs, and technical writing
• Common pitfalls and how to avoid them

Why It Matters

Markdown is the universal language of documentation — used in every README on GitHub, every Stack Overflow answer, every Hugo site (including this one), and most modern CMS platforms. DodaZIP uses Markdown for its release notes and changelog because it’s human-readable in raw form and renders beautifully as HTML. Cloud-native tools like Docker and Kubernetes use Markdown extensively for their documentation. Learning Markdown properly means you can write once and publish anywhere — websites, wikis, email, even books.

Learning Path

    flowchart LR
  A[Markdown Basics<br/>You are here] --> B[Text Formatting & Lists]
  B --> C[Links, Images & Tables]
  C --> D[Advanced: Footnotes, Tasks, HTML]
  D --> E[GFM & Real-World Usage]
  

Headings

Markdown supports six levels of headings, corresponding to HTML <h1> through <h6>.

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

Use a single # for the page title. Subheadings start at ##. Never skip levels — going from ## to #### breaks the document outline.

Bold and Italic

Text emphasis uses asterisks or underscores.

**bold text** or __bold text__
*italic text* or _italic text_
***bold and italic*** or ___bold and italic___

bold text
italic text
bold and italic

GFM allows underscore-only bold/italic inside words: un_common_ renders as un_common_.

Lists

Unordered Lists

- Item one
- Item two
  - Nested item (indent 2 spaces)
  - Another nested item
- Item three

Ordered Lists

1. First step
2. Second step
   1. Sub-step (indent 3 spaces)
3. Third step

To continue numbering after a paragraph break, use 1. — Markdown auto-numbers correctly.

Links

[visible text](https://example.com)

[link with title](https://example.com "Title text on hover")

[reference-style link][ref]

[ref]: https://example.com "Optional title"

Reference-style links keep documents readable by moving URLs to the bottom.

Images

![alt text](https://example.com/image.png)

![alt text with title](image.png "Screenshot of output")

[![clickable image](thumbnail.png)](https://example.com)

Always include alt text for accessibility. The third form creates a clickable image linking to another page.

Code Blocks

Inline Code

Use single backticks: `variable_name` renders as variable_name.

Fenced Code Blocks

Triple backticks with optional language for syntax highlighting:

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

```text
Hello, Alice!

Indented Code Blocks

Indent four spaces for a plain code block (no syntax highlighting):

    # This is a code block
    echo "Hello"

Tables

Tables are assembled with pipes and dashes. Colons control alignment.

| Left-aligned | Center-aligned | Right-aligned |
| :---         |     :---:      |          ---: |
| Cell 1       | Cell 2         | Cell 3        |
| Cell 4       | Cell 5         | Cell 6        |

Tables must have a header row and a separator row. Columns don’t need to align in the source, but aligning them improves readability.

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> > Nested blockquotes use double `>`.

This is a blockquote. It can span multiple lines.

Nested blockquotes use double >.

Horizontal Rules

Three or more dashes, asterisks, or underscores:

---
***
___

All produce a <hr> element.

Footnotes

GFM footnotes let you add references without cluttering the text.

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

[^1]: The footnote content appears at the bottom of the page.

Here’s a statement with a footnote.¹

Task Lists

Task lists with checkboxes work in GFM and most Markdown processors:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another pending task

• Completed task
• Incomplete task
• Another pending task

HTML in Markdown

You can embed raw HTML for elements Markdown doesn’t cover:

<details>
<summary>Click to expand</summary>

Hidden content here — Markdown works inside HTML blocks if separated by blank lines.
</summary>
</details>

Use HTML for: <details>, <kbd>, <sup>, <sub>, <video>, <iframe>, and custom attributes like class or id.

GitHub Flavored Markdown (GFM)

GFM adds several extensions beyond standard Markdown:

• Autolinks: www.example.com becomes a link automatically
• Strikethrough: ~~strikethrough~~ renders as strikethrough
• Emoji: :rocket: renders as :rocket: (on GitHub)
• Tables with alignment: covered above
• Task lists: covered above
• Fenced code blocks with syntax highlighting: covered above

~~This text is struck through~~
- [ ] A task list item
:fire: shows a fire emoji

Escaping Markdown Characters

Prefix special characters with a backslash to render them literally:

\*not italic\*
\[not a link\]

*not italic*

Common Mistakes

1. Not leaving a blank line before headings

Headings need a blank line before them. Without it, Markdown may treat the heading as part of the previous paragraph.

2. Mixing tab and space indentation in lists

Use spaces consistently (2 or 4 spaces for nested items). Tabs render differently across editors and break list nesting.

3. Forgetting the separator row in tables

A table without ---|--- won’t render as a table — the content shows as plain text.

4. Not escaping underscores in filenames

my_file.txt renders as my_file.txt (italic). Use my\_file.txt to show the filename literally.

5. Using heading level 1 more than once

A page should have exactly one # Title. Multiple # headings confuse screen readers and SEO crawlers.

6. Broken reference-style links

[text][ref]
<!-- Missing the [ref]: definition at the bottom — the link won't render -->

7. Over-nesting blockquotes

> > > > > > deep is hard to read. Limit blockquote nesting to 2–3 levels.

Practice Questions

1. How do you create a line break in Markdown without starting a new paragraph? End a line with two or more spaces, then press Enter. Or use <br> HTML tag.

2. What’s the difference between _italic_ and *italic*? Both render as italic. Underscores don’t work inside words (e.g., my_var renders as my_var). Asterisks work everywhere.

3. How do you create a table with right-aligned columns? Use ---: in the separator row: | Col | Right: |. The colon on the right side right-aligns.

4. What is GFM and how is it different from standard Markdown? GitHub Flavored Markdown extends standard Markdown with strikethrough, tables, task lists, auto-links, fenced code blocks, and emoji.

5. How do you prevent a link from being auto-linked? Wrap the URL in backticks: `https://example.com` renders as code, not a link.

Challenge: Write a complete Markdown document that includes a table of contents (using anchor links), at least one table with aligned columns, a task list, a footnote, a fenced code block with syntax highlighting, and an embedded HTML <details> element. Render it locally with a tool like pandoc or marked.

Mini Project — README Generator Template

Create a reusable README template in Markdown for your open-source projects:

# Project Name

> Brief one-liner describing what this project does.

## Features

- Feature one
- Feature two
- Feature three

## Quick Start

```bash
git clone https://github.com/user/project.git
cd project
make install

Usage

import project

result = project.process("input")
print(result)
# Expected: processed output

API Reference

Configuration

Create a config.yaml file in the project root:

debug: false
port: 8080
database:
  host: localhost
  port: 5432

Contributing

See CONTRIBUTING.md for guidelines.

1. Fork the repo
2. Create a feature branch
3. Submit a pull request

License

MIT © 2026 Your Name

Replace the placeholder content with your project details and you have a professional README in minutes.

## FAQ


      
What is the best Markdown editor?
      
Any text editor works — VS Code, Obsidian, Typora, or even Notepad. VS Code with the Markdown Preview Enhanced extension provides live preview, table formatting, and diagram support.
    

      
Does Markdown support syntax highlighting?
      
Yes, when you specify the language after opening triple backticks. Most Markdown renderers support dozens of languages including Python, Bash, JavaScript, HTML, and CSS.
    

      
Can I use Markdown for a book?
      
Yes. Tools like Pandoc convert Markdown to PDF, EPUB, HTML, LaTeX, and more. Many technical authors write in Markdown and convert to publication formats.
    

      
Is Markdown the same everywhere?
      
No. There’s no single Markdown standard. CommonMark aims to standardize, but GitHub, GitLab, Reddit, and Hugo each have their own extensions. Stick to CommonMark for portability.
    

      
How do I add a table of contents?
      
Some renderers auto-generate TOCs from headings. For manual TOCs, use anchor links: [Section Name](#section-name) where section-name is the heading text lowercased and hyphenated.
    

      
Why is my table not rendering?
      
Check for: missing separator row (|---|---|), unequal column counts, or missing blank lines before the table.
    

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.