What Is Markdown? A Beginner's Guide with Examples

Markdown is a lightweight markup language that lets you format text using simple punctuation characters — no HTML tags, no toolbar buttons, no mouse required. It is the standard format for README files, documentation, blog posts, note-taking apps, and developer platforms like GitHub, Reddit, and Notion. Learning it takes about ten minutes.

What is Markdown and why was it created?

Markdown was created in 2004 by John Gruber (with input from Aaron Swartz) as a way to write formatted text using plain ASCII characters that are readable even before rendering. The goal was a format that looked clean as raw text and produced clean HTML when converted.

Today, Markdown has become ubiquitous in technical writing. GitHub renders Markdown in README files, issues, and wikis. Notion, Obsidian, Ghost, Jekyll, Hugo, and most static site generators use it. Learning Markdown is one of the highest-ROI writing skills for anyone who works with technical content.

Core Markdown syntax

Here is everything you need to write well-formatted Markdown:

• Headings — Use # for H1, ## for H2,### for H3. Add a space between the hash and the text.
• Bold — Wrap text in double asterisks: **bold text**
• Italic — Wrap text in single asterisks or underscores:*italic* or _italic_
• Links — [Link text](https://example.com)
• Images — ![Alt text](image-url.jpg)
• Unordered lists — Start lines with - or *
• Ordered lists — Start lines with 1., 2., etc.
• Inline code — Wrap with backticks: `code here`
• Code blocks — Three backticks on a line above and below the code. Add a language name after the opening backticks for syntax highlighting.
• Blockquotes — Start a line with >
• Horizontal rule — Three hyphens on their own line: ---

Markdown example: before and after

Step-by-step: writing and previewing Markdown with ToolsGravity

1. Open the Markdown Editor — it shows live preview side by side with your Markdown source.
2. Type or paste your Markdown in the left panel. The right panel updates in real time to show the rendered HTML output.
3. Use the live preview to spot any syntax errors — mismatched asterisks or missing closing brackets are immediately visible.
4. Copy the rendered HTML if you need to paste it into a CMS or email editor, or copy the raw Markdown source for platforms that accept it directly.

GitHub Flavoured Markdown extras

GitHub and many other platforms support extensions beyond standard Markdown:

• Tables — Created using pipe characters (|) and hyphens for the header separator row.
• Task lists — - [ ] Unchecked task and- [x] Completed task render as checkboxes.
• Strikethrough — ~~strikethrough text~~
• Syntax highlighting — Specify a language after the opening triple backtick: ```javascript
• @mentions and #issue references — Platform-specific features on GitHub and similar tools.

Summary

Markdown is a 10-minute investment that pays dividends for years. Once you know the core syntax, writing formatted documents without touching a toolbar becomes natural. Use the ToolsGravity Markdown Editor to practise with live preview, and you will be fluent within a single session. For comparing Markdown versions, the Text Difference Checker shows exactly what changed between drafts.