The Complete Guide to Markdown

Created: January 1, 1

Updated: May 16, 2025

Read: 3 min (540 words)

Tags:

This comprehensive document showcases various heading levels and formatting options available in markdown.

Introduction to Markdown

Markdown is a lightweight markup language created by John Gruber in 2004. It’s designed to be easy to write and easy to read.

Basic Principles

The main goal of markdown is to provide a syntax that is readable as-is, without looking like it’s been marked up with tags or formatting instructions.

Philosophy Behind Markdown

Markdown was influenced by existing conventions for marking up plain text in email and usenet posts.

Design Considerations

Readability was the primary design consideration for the markdown formatting syntax.

Historical Context

Markdown drew inspiration from text-to-HTML filters like Setext, atx, Textile, reStructuredText, and Grutatxt.

Syntax Elements

Text Formatting

Markdown offers various ways to format your text.

Bold and Italic

You can make text bold or italic easily.

Combined Formatting

You can also combine these for bold and italic text.

Special Cases

In some markdown variants, you can also use underscores for emphasis.

Lists and Enumerations

Ordered Lists

First item
Second item
Third item

Nested Ordered Lists

Outer item
1. Inner item
2. Another inner item
Second outer item

List Best Practices

Keep your lists consistent in formatting for best results.

Unordered Lists

Item one
Item two
Item three

Code Blocks

Inline Code

Use backticks for inline code.

Fenced Code Blocks

1
2
def hello_world():
    print("Hello, world!")

Syntax Highlighting

Many markdown processors support language-specific syntax highlighting.

Advanced Features

Tables

Header 1	Header 2
Cell 1	Cell 2
Cell 3	Cell 4

Table Formatting

You can align columns by using colons in the separator line.

Complex Tables

Tables can contain various elements including links and formatting.

Table Limitations

Not all markdown processors support all table features.

Links and References

Inline Links

This is a link

Reference-style Links

This is a reference link

Link Best Practices

Always provide descriptive link text for accessibility.

Document Structure

Document Organization

Well-structured documents are easier to navigate.

Logical Grouping

Group related content under appropriate headings.

Nesting Depth

Don’t nest headings too deeply without good reason.

Smallest Heading Level

This is the smallest standard heading level in markdown.

Automatic Generation

Many tools can generate a TOC based on your headings.

Manual TOC

You can also create a TOC manually with links to sections.

TOC Styling

Consider styling your TOC for better readability.

Extended Syntax

Task Lists

Completed task
Incomplete task

Implementation

Task lists are supported by GitHub and other platforms.

Variations

Different markdown processors may render task lists differently.

Compatibility

Check if your target platform supports this feature.

Footnotes

Here’s a sentence with a footnote¹.

Footnote Placement

Footnotes are typically rendered at the bottom of the document.

Multiple Footnotes

You can have many footnotes² in your document³.

Footnote Limitations

Some processors don’t support footnotes natively.

Conclusion

This document has demonstrated various heading levels and content types in markdown.

Summary of Features

We’ve covered basic text formatting, lists, code blocks, tables, and more.