2024-02-14
For anyone looking to learn markdown, it's clear there is a lot to cover from the basics of syntax to more advanced features.
The good news is this post will break down everything you need to know about markdown in simple terms, from what it is to best practices for using it effectively.
You'll get an essential overview of basic and extended markdown syntax, see examples of how to format headings, lists, links, images, and more, as well as learn handy tools and tips for previewing, converting, and automating markdown in your workflow.
Markdown is a lightweight markup language that allows users to write using simple plaintext formatting, which is then converted to HTML. It's commonly used for documentation, readme files, forum posts, and more thanks to its simplicity and portability. This guide will provide an overview of Markdown's basic and extended syntax elements.
Markdown was created in 2004 by John Gruber as a simple way to write formatted text that could easily be converted to HTML. The key benefit of Markdown over writing HTML directly is readability - Markdown uses plaintext with simple formatting like *italics* and **bold** that is very easy to read and write. This makes Markdown a popular choice for documentation, readme files, wikis, forums, and more.
Since Markdown is just plaintext, Markdown files have the .md or .markdown file extension and can be opened by any text editor. They can then be converted ("rendered") to HTML using a Markdown application. Markdown is now supported across most platforms and services like GitHub, Bitbucket, Reddit, and more.
There are several key reasons Markdown has become a popular lightweight markup language:
Markdown Toolbox
*italics* is very easy to read and write in plaintextMarkdown preview functionality is now common in most Markdown editors. This allows you to write Markdown syntax on the left side of the screen and view the rendered HTML output live on the right side. This gives writers a WYSIWYG (what you see is what you get) experience when working with Markdown documents.
Markdown has a simple plaintext formatting syntax that is designed to be readable and easy to learn. This guide will cover Markdown syntax basics like:
# H1, ## H2*italics*, **bold**[text](https://example.com)It will also cover some extended syntax elements:
:smile:Now that the basics of Markdown have been introduced, the next sections will provide specific examples and recommendations for properly structuring and formatting Markdown documents.
Markdown is a lightweight markup language that allows you to format text using simple syntax. Mastering basic Markdown syntax allows you to quickly structure and style documents without needing to use cumbersome word processing software.
You can create six levels of headings in Markdown, using the number sign (#) followed by a space. The number of number signs you use corresponds to the heading level:
# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6
Headings help create an outline and logical structure for your document. Use heading levels judiciously to clearly delineate sections in your writing.
To bold text in Markdown, add two asterisks or underscores before and after the words you want to bold:
**This text is bold**
__This text is also bold__
For italics, use one asterisk or underscore around the text:
*This text is in italics*
_This text is also in italics_
Bold and italics allow you to highlight important concepts or add emphasis. Use them sparingly for maximum effect.
To create a blockquote that cites text from another source, start the line with a right angle bracket (>):
> This entire paragraph is a blockquote. I am citing source material and commentary from elsewhere to support my writing.
>
> You can have multiple lines within a single blockquote, as long as each line starts with the angle bracket.
Blockquotes are useful for excerpting relevant passages from research when writing academic papers or articles.
Markdown supports both ordered/numbered and unordered/bulleted lists.
To create an unordered list, preface each item with an asterisk (*), plus sign (+), or hyphen (-):
* Item 1
* Item 2
* Nested Item 1
* Nested Item 2
+ Item 3
- Item 4
For ordered/numbered lists, use numbers followed by periods for each item:
1. Item 1
2. Item 2
3. Item 3
1. Nested Item
2. Nested Item
Lists help organize related concepts into scannable vertical stacks of information. They break up walls of text and improve readability.
To denote inline snippets of code within a sentence, enclose the code in backticks (`):
The `printf()` function prints output to the console.
For larger, multi-line code blocks like code examples, encapsulate the code in triple backticks (```) on lines before and after the code:
```
// JavaScript code example
function helloWorld() {
console.log("Hello world!");
}
</code></pre>
<p>Code blocks are useful for demonstrating programming concepts and code syntax. The backticks help distinguish code from normal text paragraphs.</p>
<p>Mastering these basic building blocks unlocks the ability to quickly write Markdown-formatted documents. With a little practice, Markdown can become an indispensable part of your writing toolkit.</p>
<h6 id="sbb-itb-0cbb98c" class="sb-banner" style="color:transparent!important;line-height:0!important;padding:0!important;margin:0!important;">sbb-itb-0cbb98c</h6><h2 id="leveraging-extended-markdown-syntax" tabindex="-1">Leveraging Extended Markdown Syntax</h2>
<p>Markdown offers a robust set of extended syntax and formatting options to enhance documents beyond basic text formatting. By leveraging specifications like CommonMark and <a href="https://www.markdowntoolbox.com/blog/cheat_sheet_github_style_markdown/">GitHub Flavored Markdown</a> (GFM), writers can embed rich content, create complex layouts, and customize text styling.</p>
<h3 id="links-%26-images%3A-embedding-content-with-markdown" tabindex="-1">Links & Images: Embedding Content with Markdown</h3>
<p>Adding images and hyperlinks in Markdown is straightforward using a simple syntax:</p>
<pre><code>[text to display](URL)
</code></pre>
<p>The text in square brackets is what displays on the page. The URL in parentheses points to the destination for links or image source.</p>
<p>For example:</p>
<pre><code>[Visit the Markdown Guide](https://www.markdownguide.org)
</code></pre>
<p><a href="https://www.markdownguide.org" target="_blank">Visit the <a href="https://www.markdowntoolbox.com/">Markdown Guide</a></a></p>
<p>Tip: Reference-style links help reduce clutter for repeated links.</p>
<h3 id="tables%3A-crafting-markdown-tables-with-precision" tabindex="-1">Tables: Crafting Markdown Tables with Precision</h3>
<p>The <a href="https://www.markdowntoolbox.com/blog/how_do_i_make_table_multiline_in_markdown/">Markdown table</a> syntax uses pipes <code>|</code> as column separators and hyphens <code>-</code> for table headings:</p>
<pre><code>| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Row 1 | Data | Here |
| Row 2 | More | Data |
</code></pre>
<p>Renders as:</p>
<table>
<thead>
<tr>
<th>Column 1</th>
<th>Column 2</th>
<th>Column 3</th>
</tr>
</thead>
<tbody>
<tr>
<td>Row 1</td>
<td>Data</td>
<td>Here</td>
</tr>
<tr>
<td>Row 2</td>
<td>More</td>
<td>Data</td>
</tr>
</tbody>
</table>
<p>For aligned columns, add colons <code>:</code> to column headings:</p>
<pre><code>| Left Aligned | Center Aligned | Right Aligned |
| :----------- |:-------------:| ------------:|
| Data | Data | Data |
</code></pre>
<h3 id="fenced-code-blocks%3A-syntax-highlighting-in-markdown" tabindex="-1">Fenced Code Blocks: Syntax Highlighting in Markdown</h3>
<p>Surround code snippets with triple backticks <code>```</code> to render a fenced code block with automatic syntax highlighting:</p>
<pre><code>```python
print("Hello World!")
Renders as:
print("Hello World!")
Specify a language after the backticks to enable syntax highlighting for that language.
Clarify content with footnotes referenced in the document using inline square brackets and numbers [1]. Define the footnote at the bottom using brackets, number, colon, and text:
Here is some text with a footnote.[1]
[1]: Here is the footnote definition.
Renders as:
Here is some text with a footnote.[1]
[1]: Here is the footnote definition.
GFM adds syntax to strikethrough text with double tildes ~~ and highlight text with equal signs ==:
~~Mistaken text.~~
==Key point== to remember.
Renders as:
Mistaken text.
Key point to remember.
These extensions help create more visually rich documents in Markdown.
Markdown is a versatile markup language that can be extended and customized to suit different needs. Here are some helpful tools and Markdown variants to enhance productivity:
Popular Markdown editors provide useful features like live previews, syntax highlighting, file management and more:
Evaluate based on price, platform, customizability when choosing an editor.
Use online tools to instantly preview Markdown without installing any software:
Great for quick previews or sharing with others.
Flexible Markdown converters like Pandoc, Markdown Monster handle various file types:
Choose converter based on integration needs.
Streamline Markdown workflows with programming libraries like:
Helpful for developers to manipulate Markdown at scale.
Extended Markdown formats add features like:
Ideal for complex documents like scientific papers or technical manuals.
Markdown is a versatile markup language that can enhance workflows for writers, developers, students, and anyone working with text. With this guide covering markdown's basic syntax, you now have the foundation to start implementing markdown in your projects.
Here's a quick recap of some of the key topics we explored:
As you continue your markdown journey, refer back to this guide anytime you need a refresher. And explore some of the additional resources below to level up your skills:
The world of markdown has a lot more to offer beyond the basics - but you now have the core knowledge to unlock markdown's versatility and take your text formatting to the next level.