Markdown Guide: Learn Markdown from Scratch
A beginner-friendly introduction to markdown. By the end of this guide you will understand what markdown is, why people use it, and how to write your first formatted document.
What is Markdown?
Markdown is a lightweight markup language that lets you format plain text using simple symbols. It was created by John Gruber in 2004 with the goal of making text that is easy to read in its raw form and easy to convert into HTML for the web.
Instead of clicking buttons in a toolbar to make text bold or create a heading, you type simple characters like ** for bold and # for headings. The result is a plain text file that any computer can open, but that can also be rendered as a beautifully formatted document.
Today, markdown is used by millions of people for everything from developer documentation to personal notes. If you have ever written a README file on GitHub or formatted a message on Reddit, you have already used markdown.
Why Use Markdown?
Portable
Markdown files are plain text. You can open them on any operating system, in any text editor, without special software.
Platform-independent
Your content is not locked into any proprietary format. Switch tools anytime without losing your formatting.
Future-proof
Plain text files will always be readable. Unlike binary formats that require specific software versions, markdown files will open decades from now.
Widely supported
GitHub, GitLab, Reddit, Discord, Notion, Obsidian, VS Code, and hundreds of other platforms support markdown natively.
How Does Markdown Work?
The markdown workflow has three steps:
- Write your content in plain text using markdown syntax (# for headings, ** for bold, etc.).
- Process the file through a markdown parser. The parser reads your symbols and converts them into structured output.
- Output the result as HTML, PDF, or another format ready for display or publishing.
For example, when you write **hello** in markdown, the parser converts it to <strong>hello</strong> in HTML, which your browser renders as hello.
Your First Markdown Document
Let us write a simple document together. Copy the example below and paste it into our markdown editor to see the formatted result instantly.
# My First Document
This is a paragraph of text. Markdown lets you write
**bold text**, *italic text*, and [links](https://example.com).
## Shopping List
- Apples
- Bread
- Coffee
## Notes
> Markdown is simple to learn and powerful to use.
That is all you need to get started!That is everything you need to write a formatted document. The # symbol creates headings, ** makes text bold, * makes it italic, dashes create bullet lists, and > creates blockquotes.
Where to Use Markdown
Markdown shows up in more places than you might expect. Here are the most common use cases:
- -Documentation - README files, API docs, wikis, and knowledge bases.
- -Notes - Personal and team notes in apps like Obsidian, Notion, and Bear.
- -Websites - Static site generators like Next.js, Hugo, Jekyll, and Gatsby use markdown for content.
- -Messages - Slack, Discord, Reddit, and GitHub comments all support markdown formatting.
- -Email - Some email clients and tools let you compose messages in markdown.
Markdown Flavors
Over the years, different organizations have created their own extensions to the original markdown specification. Here are the most important ones:
CommonMark
A strict, well-defined specification that removes ambiguity from the original markdown rules. It serves as the foundation for many modern parsers.
GitHub Flavored Markdown (GFM)
Built on top of CommonMark, GFM adds tables, task lists, strikethrough, and auto-linked URLs. It is the standard on GitHub and widely adopted elsewhere.
MultiMarkdown
Extends the original spec with metadata, footnotes, tables, citations, and cross-references. Popular in academic writing.
What Tools Support Markdown?
You can write markdown in any text editor, but dedicated tools give you live preview, syntax highlighting, and export options. Our markdown tools hub includes a free online editor, table generator, PDF converter, HTML converter, and formatter that all work in your browser with no signup required.
Popular desktop editors include VS Code, Obsidian, Typora, and iA Writer. For quick tasks, our browser-based tools let you start writing immediately.
Next Steps
You now know what markdown is, why people use it, and how to write a basic document. Here is where to go next:
Frequently Asked Questions
What is markdown used for?
Markdown is used for writing documentation, README files, blog posts, notes, technical articles, and messages on platforms like GitHub, Reddit, and Discord. It is the standard format for developer documentation and is supported by most content management systems.
Is markdown hard to learn?
No. Markdown was designed to be as easy to read and write as possible. You can learn the essential syntax (headings, bold, italic, links, and lists) in under 10 minutes. The plain text format means you do not need any special software to get started.
What is the difference between markdown and HTML?
Markdown is a simplified writing format that gets converted into HTML. While HTML uses tags like <strong> and <a>, markdown uses symbols like ** for bold and [text](url) for links. Markdown is faster to write and easier to read, but HTML offers more control over layout and styling.
What software do I need to write markdown?
You can write markdown in any plain text editor, including Notepad, TextEdit, or VS Code. For a better experience, use a dedicated markdown editor with live preview. Our free online markdown editor lets you write and preview markdown instantly in your browser.
Can I convert markdown to other formats?
Yes. Markdown can be converted to HTML, PDF, Word documents, slides, and many other formats. Tools like Pandoc handle complex conversions. Our site offers free markdown to HTML and markdown to PDF converters that work directly in your browser.