Markdown Syntax | Basic Tutorial

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

John Gruber

John Gruber, the author of MD, designed Markdown’s formatting syntax with the goal to make it as readable as possible. Markdown is a simple markup language that allows you to format plain text. It is a way to write content for the Web. Markdown language is simple to learn; it has minimal extra characters, so you can quickly write and make fewer errors.

Basic Markdown Syntax

This article provides information on the main Markdown elements, details and examples of the Markdown syntax. A full list of all the Markdown syntax is declared in the core Markdown specification and GitLab Flavored Markdown variation. All these features are supported by Aspose.HTML out-of-the-box.

Headers

Markdown supports two styles of headers, Setext and atx: To create an atx-style heading, add signs (#) at the start of the line. The number of signs you use should correspond to the heading level. Note: Always put a space between the number signs (#) and the heading name.

Alternatively, to create a setext-style heading, on the line below the text, add any number of == characters for heading level 1 or -- characters for heading level 2.

Markdown Syntax HTML Rendered
# This is a Heading level 1 <h1>This is a Heading level 1</h1>

This is a Heading level 1

## This is a Heading level 2 <h2>This is a Heading level 2</h2>

This is a Heading level 2

### This is a Heading level 3 <h3>This is a Heading level 3</h3>

This is a Heading level 3

###### This is a Heading level 6 <h6>This is a Heading level 6</h6>
This is a Heading level 6
This is a Heading level 1
===================
<h1>This is a Heading level 1</h1>

This is a Heading level 1

This is a Heading level 2
- - - - - - - - - - - - - - - - - - -
<h2>This is a Heading level 2</h2>

This is a Heading level 2

Emphasis

Markdown treats asterisks * and underscores (_) as indicators of emphasis. To make text bold and italic at the same time, add three asterisks or underscores before and after the word or phrase. To make the middle of a word bold and italicize for emphasis, add three asterisks without spaces around the letters.

Markdown Syntax HTML Rendered
*single asterisks* <em>single asterisks</em> single asterisks
_single underscores_ <em>single underscores</em> single underscores
**double asterisks** <strong>double asterisks</strong> double asterisks
__ double underscores__ <strong>double underscores</strong> double underscores
***Bold and Italic*** <strong><em>Bold and Italic</em></strong> Bold and Italic
___Bold and Italic___ <strong><em>Bold and Italic</em></strong> Bold and Italic
Make text bold***and***italic at the same time Make text bold<strong><em>and</em></strong>italic at the same time Make text boldanditalic at the same time

Blockquotes

Markdown language uses email-style > characters for blockquote. So, for blockquote creating, you should put a sign > before the first line of a hard-wrapped paragraph. If a blockquote contains multiple paragraphs, add a > on the blank lines between the paragraphs. Moreover, blockquotes can include other Markdown elements, including headers, emphasis, lists, or code snippets: Let’s consider some usage examples:

Markdown Syntax Rendered
> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
alt text
> ## This is a header.
>
> 1. This is the first list item.
> 2. This is the second list item.
>
> Here’s some example code:
>
> using var document = new HTMLDocument();
alt text

Markdown code blocks

Code

To indicate a span of code in the article text, wrap it with backtick quotes (`):

Markdown Syntax HTML Rendered
Load the HTML file using `HTMLDocument` class Load the HTML file using <code>HTMLDocument</code> class Load the HTML file using HTMLDocumentclass
`Use code in your Markdown file.` <code>Use code in your Markdown file.</code> Use code in your Markdown file.

Code Blocks

To make a code block in Markdown, indent every line of the block by at least 4 spaces or 1 tab. In this example, leading spaces are indicated by periods: (⋅):

Markdown Syntax HTML Rendered
This is a normal paragraph. <p>This is a normal paragraph.</p>

This is a normal paragraph.

⋅⋅⋅⋅This is a Markdown code block. <pre>This is a Markdown code block.</pre>
This is a Markdown code block.

Lists

Unordered Lists

Markdown supports ordered (numbered) and unordered (bulleted) lists. Unordered lists use asterisks, pluses, and hyphens interchangeably as list markers. Begin lines with *, +, or -. To create a nested list, indent one or more items:

Markdown Syntax
HTML
Rendered
- First item
- Second item
- Third item
- Fourth item
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
<li>Fourth item</li>
</ul>
  • First item
  • Second item
  • Third item
  • Fourth item
* First item
* Second item
* Blue
* Black
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
<li>Fourth item</li>
</ul>
  • First itemd
  • Second item
  • Third item
  • Fourth item
+ First item
+ Second item
+ Third item
+ Fourth item
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
<li>Fourth item</li>
</ul>
  • First itemd
  • Second item
  • Third item
  • Fourth item

Ordered Lists

To create an ordered list, add line items with numbers followed by periods. The list should start with number one. Then other numbers you use to mark the list have no impact on the HTML output Markdown gives.

Markdown Syntax
HTML
Rendered
1. Red
1. Green
1. Blue
1. Black
<ol>
<li>Red</li>
<li>Green</li>
<li>Blue</li>
<li>Black</li>
</ol>
  1. Red
  2. Green
  3. Blue
  4. Black
1. Red
2. Green
3. Blue
4. Black
<ol>
<li>Red</li>
<li>Green</li>
<li>Blue</li>
<li>Black</li>
</ol>
  1. Red
  2. Green
  3. Blue
  4. Black
1. Red
5. Green
3. Blue
8. Black
<ol>
<li>Red</li>
<li>Green</li>
<li>Blue</li>
<li>Black</li>
</ol>
  1. Red
  2. Green
  3. Blue
  4. Black

Images

Inline image Markdown syntax looks like this:

![Alt text for image](/path/to/img.jpg)
Example:
![Ananuri Fortress Complex in Georgia](../Georgia.jpg)

You should add an exclamation mark (!), followed by alt text in square brackets, and the URL or path to the image in the parentheses. Where Alt text for image is a brief description of the image and /path/to/img.jpg is a relative path to the image. Alternate text is useful if the image can’t render. The rendered output for the example Georgia.jpg looks like this:

Ananuri Fortress Complex in Georgia

Extended Markdown Syntax

To create a link, write the link text in square brackets, and then follow it with the URL in parentheses. Links syntax looks like this:

Use [Markdown Converter](https://products.aspose.app/html/conversion/md) for converting Markdown files to a variety of popular formats.

The rendered link text looks like this:

Use Markdown Converter for converting Markdown files to a variety of popular formats.

URLs and Email Addresses

To quickly turn a URL or email address into a link, write it in angle brackets:

<https://docs.aspose.com/html/net/converting-between-formats/>
<html@example.com>

The rendered links to the URL and email address look like this:

https://docs.aspose.com/html/net/converting-between-formats/

html@example.com

Image as a link

To add a link to an image, enclose the Markdown for the image in brackets, and then add the link in parentheses. Markdown syntax for an image as a link looks like this:

 [![Text "Banner MD to PDF Converter"](../markdown-to-pdf/md-to-pdf.png)](https://products.aspose.app/html/conversion/md-to-pdf)

The rendered image as a link looks like this:

Text “Banner MD to PDF Converter”

Markdown table syntax

Tables are often the best way to present some data, but formatting tables in Markdown is one of the trickiest. A table in Markdown consists of two parts: the header and the rows of data in the table. Tables are created using pipes (|) and hyphens (-). Use three or more hyphens (–) to create each column’s header, and use pipes (|) to separate each column. The colons (:) used to align cell contents. The colons alongside to the left of the hyphen, cause the column to be left-aligned and etc.

Here is an example of a Markdown table syntax:

| Header 1       | Header 2           | Header 3       |
| :------------- | :----------------: | -------------: |
| Cell Content 1 | Cell Content 2     | Cell Content 3 |
| Text           | Some long data here| Data           |

The rendered table looks like this:

Header 1 Header 2 Header 3
Cell Content 1 Cell Content 2 Cell Content 3
Text Some long data here Data

GitLab Flavored Markdown lets you create simple, easy-to-read tables. You can easily add Markdown syntax to tables, such as bold, italic, code blocks, HTML tags and more.