Markdown Toolbox Logo Markdown Toolbox
Home
Blog

Markdown Guide Basic Syntax Explained

2024-02-14

Markdown Guide Basic Syntax Explained

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.

Introduction to Markdown: The Essential Guide

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.

What is Markdown? Understanding the Basics

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.

Why Use Markdown? Benefits and Markdown Preview

There are several key reasons Markdown has become a popular lightweight markup language:

  • Readability - Markdown formatting like *italics* is very easy to read and write in plaintext
  • Portability - Markdown files use the plaintext .md extension so can be opened on any device
  • WYSIWYG Editors - Many Markdown editors now provide live previews so you can see rendered HTML as you write
  • Platform Support - Markdown is supported across most major platforms and services like GitHub, Bitbucket, Reddit etc.

Markdown 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 Syntax Overview: From Basics to Extended Syntax

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:

  • Headings - # H1, ## H2
  • Emphasis - *italics*, **bold**
  • Lists - unordered, ordered, nested
  • Links - [text](https://example.com)
  • Images - ![alt](image.jpg)

It will also cover some extended syntax elements:

  • Code Blocks - multi-line code snippets
  • Tables - Markdown table syntax
  • Blockquotes - quoted text callouts
  • Emoji support - :smile:
  • and more...

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.

Mastering Basic Markdown Syntax

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.

Headings: Creating Structure in Your Document

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.

Bold & Italics: Adding Emphasis to Text

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.

Blockquotes: Citing Sources with Markdown

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.

Lists: Organizing Content with Ordered and Unordered Lists

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.

Code: Inline Snippets and Markdown Code Blocks

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 &amp; 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)
![alt text](imageURL)
</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)
![Markdown logo](https://markdownguide.org/assets/img/markdown-guide-logo.png)
</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(&quot;Hello World!&quot;)

Renders as:

print("Hello World!")

Specify a language after the backticks to enable syntax highlighting for that language.

Footnotes: Providing Context with Markdown

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.

Strikethrough & Highlight: Extended Formatting in Markdown

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.

Utilizing Markdown Tools & Extensions

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:

Choosing a Markdown Editor: Tools for Every Writer

Popular Markdown editors provide useful features like live previews, syntax highlighting, file management and more:

  • Typora - minimalistic, seamless live preview
  • Visual Studio Code - robust extension ecosystem
  • Atom - highly customizable with Markdown plugins
  • Markdown Monster - built-in converter and file management

Evaluate based on price, platform, customizability when choosing an editor.

Online Markdown Previews: Instant Rendering of Markdown

Use online tools to instantly preview Markdown without installing any software:

  • Dillinger - intuitive editor with export options
  • StackEdit - supports Markdown extras like diagrams
  • Markdown Live Preview - simple real-time rendering

Great for quick previews or sharing with others.

Converting Markdown: Tools for Every Format

Flexible Markdown converters like Pandoc, Markdown Monster handle various file types:

  • Word, PDF, HTML, ePub
  • Batch conversion automation
  • Customizable with templates
  • Python and Node.js modules also available

Choose converter based on integration needs.

Automating Markdown: Libraries & Modules for Efficiency

Streamline Markdown workflows with programming libraries like:

  • Python-Markdown - PyPI library for file processing
  • markdown-it - Node.js module with syntax extensions
  • Pandoc filters - integrate other languages into Markdown

Helpful for developers to manipulate Markdown at scale.

Exploring MultiMarkdown and Markdown Extra: Advanced Features

Extended Markdown formats add features like:

  • Citations, cross-references
  • Table of contents
  • Metadata header
  • Definition lists
  • Footnotes

Ideal for complex documents like scientific papers or technical manuals.

Conclusion: Wrapping Up Your Markdown Journey

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:

  • Basic formatting like headings, lists, bold, italics, links, images, and code blocks
  • Extended syntax elements like tables, strikethrough, task lists, and emoji
  • Converting markdown to HTML for web publishing
  • Markdown apps and tools like editors, live previews, and file converters

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.