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 Markdown, 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.

> ## 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();

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 `HTMLDocument`class
`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>

Red
Green
Blue
Black

1. Red
2. Green
3. Blue
4. Black

<ol>
<li>Red</li>
<li>Green</li>
<li>Blue</li>
<li>Black</li>
</ol>

Red
Green
Blue
Black

1. Red
5. Green
3. Blue
8. Black

<ol>
<li>Red</li>
<li>Green</li>
<li>Blue</li>
<li>Black</li>
</ol>

Red
Green
Blue
Black

Images

Inline image Markdown syntax looks like this:

![Alt text for image](/path/to/img.png)
Example:
![Text "Ananuri Fortress Complex in Georgia"](georgia-castle.png)

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.png is a relative path to the image. Alternate text is useful if the image can’t render. The rendered output for the example georgia-castle.png looks like this:

Text “Ananuri Fortress Complex in Georgia”

Extended Markdown Syntax

Links

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:

1<https://docs.aspose.com/html/net/converting-between-formats/>
2<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:

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

The rendered image as a link looks like this:

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:

1| Header 1       | Header 2           | Header 3       |
2| :------------- | :----------------: | -------------: |
3| Cell Content 1 | Cell Content 2     | Cell Content 3 |
4| 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.

Aspose.HTML for .NET library provides a Markdown parsing API for the C# platform. You can programmatically create, edit, save, merge, convert MD files to other formats, and add links, lists, code blocks, images, and other elements into Markdown files.

Convert Markdown to Image SVG Converter