Markdown is the unofficial writing language of the internet. GitHub READMEs, dev blog posts, documentation sites, Slack messages, Reddit comments, and note-taking apps all support Markdown. Once you learn it, you can format text beautifully in dozens of tools without ever touching a rich-text editor or writing HTML by hand. This guide covers everything a beginner needs to know, from basic syntax to tables and code blocks, with examples you can try immediately.
What Is Markdown?
Markdown is a lightweight markup language created by John Gruber in 2004. It uses simple punctuation characters to indicate formatting. For example, surrounding a word with asterisks makes it bold, and starting a line with a hash creates a heading.
The philosophy behind Markdown is readability. A Markdown file should be easy to read even in its raw, unrendered form. This makes it perfect for plain-text environments like terminals, code editors, and version control diffs where rich formatting is unavailable.
Markdown files use the <code>.md</code> or <code>.markdown</code> extension. When rendered (by GitHub, a static site generator, or a preview tool), the punctuation is converted to HTML, producing formatted headings, bold text, links, images, and more.
Headings, Paragraphs, and Line Breaks
Headings are created with hash symbols. One hash for an H1, two for H2, and so on up to six levels:
<code># Heading 1 ## Heading 2 ### Heading 3</code>
Paragraphs are simply blocks of text separated by a blank line. Markdown ignores single line breaks within a paragraph and treats them as spaces. To force a line break without starting a new paragraph, end the line with two spaces or use a backslash.
Horizontal rules are created with three or more hyphens, asterisks, or underscores on a line by themselves:
<code>---</code>
These are useful for visually separating sections in long documents.
Emphasis: Bold, Italic, and Strikethrough
Markdown offers several inline formatting options:
<strong>Bold:</strong> Wrap text in double asterisks or double underscores. <code>**bold text**</code> or <code>__bold text__</code>
<strong>Italic:</strong> Wrap text in single asterisks or single underscores. <code>*italic text*</code> or <code>_italic text_</code>
<strong>Bold and italic:</strong> Use three asterisks. <code>***bold and italic***</code>
<strong>Strikethrough:</strong> Wrap text in double tildes. <code>~~deleted text~~</code>
The asterisk syntax is generally preferred over underscores because underscores can conflict with words_that_contain_underscores in some parsers.
Links, Images, and Lists
<strong>Links</strong> use square brackets for the text and parentheses for the URL: <code>[ToolboxHub](https://toolbox-hub-omega.vercel.app)</code>
You can add a title attribute in quotes after the URL: <code>[Link](url "Title")</code>.
<strong>Images</strong> use the same syntax with an exclamation mark in front: <code></code>
<strong>Unordered lists</strong> use hyphens, asterisks, or plus signs: <code>- Item one - Item two - Nested item</code>
<strong>Ordered lists</strong> use numbers followed by a period: <code>1. First 2. Second 3. Third</code>
Markdown automatically renumbers ordered lists, so you can use <code>1.</code> for every item and the renderer will display the correct sequence. Nesting is achieved by indenting with two or four spaces.
Code: Inline and Blocks
For developers, code formatting is one of Markdown's most valuable features.
<strong>Inline code</strong> is wrapped in single backticks: <code>`const x = 42`</code> renders as <code>const x = 42</code>.
<strong>Code blocks</strong> use triple backticks (fenced code blocks) with an optional language identifier for syntax highlighting:
<code>```javascript function greet(name) { return `Hello, ${name}!`; } ```</code>
Most renderers support syntax highlighting for dozens of languages including JavaScript, Python, TypeScript, HTML, CSS, SQL, Bash, and many more. The language identifier after the opening backticks tells the renderer which grammar to use.
You can also create code blocks by indenting every line with four spaces, but the fenced syntax is more flexible and widely preferred.
Tables, Blockquotes, and Task Lists
<strong>Tables</strong> are created with pipes and hyphens:
<code>| Feature | Supported | | ------- | --------- | | Bold | Yes | | Tables | Yes |</code>
Align columns by adding colons in the separator row: <code>:---</code> for left, <code>:---:</code> for center, <code>---:</code> for right.
<strong>Blockquotes</strong> use the greater-than symbol: <code>> This is a quote. > It can span multiple lines.</code>
Blockquotes can be nested by adding additional <code>></code> symbols.
<strong>Task lists</strong> (supported by GitHub and many apps) use brackets: <code>- [x] Completed task - [ ] Incomplete task</code>
These render as interactive checkboxes on platforms like GitHub, making them perfect for tracking to-do items in issues and pull requests.
Preview Your Markdown Online
The best way to learn Markdown is to write it and see the result immediately. The free <a href="/tools/markdown-preview">ToolboxHub Markdown Preview</a> lets you do exactly that:
1. Open <a href="/tools/markdown-preview">/tools/markdown-preview</a>. 2. Type or paste Markdown in the editor on the left. 3. See the rendered HTML output on the right in real time.
This side-by-side view is perfect for learning because you can experiment with syntax and instantly see the effect. The tool runs in your browser with no sign-up required.
You might also find the <a href="/tools/word-counter">Word Counter</a> useful for checking the length of your Markdown documents, or the <a href="/tools/json-formatter">JSON Formatter</a> for formatting JSON code blocks that appear in your documentation.