Rajendra Gupta

Learn Markdown language for SQL Notebooks in Azure Data Studio

February 26, 2020 by

Microsoft supports SQL Notebooks in Azure Data Studio. It is an exciting feature that allows creating a notebook for multiple languages such as Python, SQL, PowerShell. You might have heard about the Jupyter notebook. It is a popular web-based notebook that provides rich programming language support. SQL Notebook is an inspiration for the Jupyter notebook.

To follow along nicely, I would recommend going through the below articles:

You should also use the latest version of Azure Data Studio.

  • Latest version: 1.15.0
  • Release date: February 15, 2020
  • Download: Microsoft

Download the installer per the platform: Windows, macOS or Linux.

Download the installer for Azure Data Studio

Overview of Markdown language

SQL Notebooks uses markdown language for text formatting. If you are familiar with GitHub, it uses markdown language for all forms such as read me file. We can do text formatting with its simplified method. It helps us to write easy-to-read, easy-to-write plain text with structurally valid XHTML.

HTML is a popular programming language. We use tags in HTML for defining text into various formats. For example, for a H1 heading, we use <h1>Title</h1> tags.

Launch Azure Data Studio and open a SQL notebook.

SQL notebook

It opens a blank notebook, as shown below.

blank notebook Click on +Text and it opens a text block for you.

Click on +Text Let’s do various formatting using markdown language.

Format Headings

The first step for a document is heading. We also require heading for different sections in the article. We want a different size for the headings and subheadings.

We use hash sign (#) preceding with the text and the number of # defines the heading font level. It supports up to six levels of headings.

You can view difference in these heading font size in the following image.

# SQL Notebook 

## SQL Notebook

### SQL Notebook

#### SQL Notebook

##### SQL Notebook

###### SQL Notebook

Headings in SQL Notebook

We can also use the following markdown code for first and second-level headings.

SQL Notebooks


SQL Notebooks



Add Paragraphs

We write documents in many paragraphs. To specify a paragraph in the markdown language, leave an empty line. In the following example, we give an empty line after Hello but did not give any empty line after team. In the output, markdown language understands an empty line at the end of the paragraph. It treats the last two lines as a single paragraph.


Format Bold text

We can enclose the text in double star( **), and it highlights text in bold format.

Bold text

Format Italic text

Enclose the text in single star(*) and it changes the format for text in italic.

Italic text

Format Bold and Italic text

We can combine both bold and italic format for text by enclosing text with three starts ***

Bold and Italic text

Create bullet lists in the notebook

You might be familiar with creating bullet lists in Microsoft Word document. We can create similar lists using markdown language.

Unordered lists

Use prefix * followed by a space for the unordered lists. We can also create a nested list using this prefix.

Create bullet Lists

In the above image, feature 1 and feature 2 are at the same level. Due to this, in markdown, we get a similar bullet for both.

We can create a further nested list by changing the position of the text, as shown below.

Create nested bullet Lists

Ordered list

The ordered list shows the sequence number for each line. We specify a number for each line, and it creates an ordered list.

Create ordered bullet Lists

We can easily configure both ordered and unordered list combining both stars (*) and numbers as shown below

Combination of ordered and unordered list


We can add a word as a code format by enclosing it in backticks (`).



We can add a greater than(>) symbol in beginning of a paragraph, and it turns into a blockquote element.


To add multiple lines in the same blockquote, add > in each line.

multiple lines in the blockquote

Nested Blockquotes

Sometimes you require nested blockquotes as well. We can add >> for the nested blockquotes as shown below. Nested Blockquotes

Specifying URL hyperlink

Sometimes, we include hyperlinks in a document as well so that users can click on the hyperlink and go to the reference website.

We can create both inline and reference style links using the markdown language.

Inline hyperlink

Inline hyperlinks are similar to a word document hyperlink. We specify it in the following format.

[Text to display] (URL)

Specifying URL

Reference Style Links

We can also create a referenced style links in markdown language. Suppose we want to use the same URL hyperlink in multiple places like reference articles from Microsoft Word. We can either create an inline hyperlink each time or use a reference style hyperlink.

In the following example, we specify [Link 1] text multiple time and later referenced that text for the URL. It saves efforts for us to specify inline hyperlink and users can also know that all these references are from a single URL. You can see these reference style hyperlink on a website like Wikipedia.

Reference Style Links

Image reference

We can reference an image using an exclamation mark (!) symbol and add an alt-text in the square brackets along with the image URL. In the following example, we can see the Wikipedia logo in SQL Notebook using markdown language.

![Wikipedia](https://upload.wikimedia.org/wikipedia/en/8/80/Wikipedia-logo-v2.svg “Wikipedia”)

Image reference

We can also create a reference style image reference in the markdown similar to the reference URL. For this, we can use the below format.

[logo]: https://upload.wikimedia.org/wikipedia/en/8/80/Wikipedia-logo-v2.svg “Wikipedia”

Image reference style

Add Horizontal Rule

We can create a horizontal rule by enclosing text *** symbol(three or more) followed by a line break. You can see a horizontal rule in the below image.

Horizontal Rule

Specify email in the text

We can enclose email address in <> symbol so that it appears as a hyperlink in the output.

Specify email in the text

Escape characters

As I explained earlier, we use * for an unordered list. Suppose we want to print this character as well in the output. In this case, add a backslash to skip the behavior of * in markdown language.

Escape characters

Add Tables in a notebook

Markdown does not specify code for tables, but still, we can create them.

  • We use colons to align the columns
  • We require at least three dashes to separate column headers
  • We can use outer pips for separating columns

Here is the markup code for an employee table with three columns- EmployeeName, Location and designation.

| EmployeeName        | Location           | Designation  |

| ————- |:————-:| —–:|

| Rajendra Gupta      | India | Sr. Consultant |

| Kusum Agarwal      | India     |   Physiotherapist |

| Akshita Gupta | India    |    Intern |


Add Videos in the notebook

We do not have a direct method to add a video link in the markdown language. But, there is always a workaround.

Follow the below steps to add a video reference in SQL notebook.

  • Extract a thumbnail of the video you wish to create a reference. You can either take a screenshot of the video or use third-party tools for the thumbnail of it
  • Create a reference link for the video

For this demonstration, I am using the YouTube video link and using an image for thumbnail purposes.

[![SQL Server 2019](C:\Users\rajen_000\Pictures\SQL2019.JPG)](http://www.youtube.com/watch?v=mKlAyvvR70I “SQL 2019”)

It renders an image, as shown below.

Add Videos in the notebook

Click on the image, and it asks your permission to open the external Website.

permission to open the external site

Click open, and it plays the YouTube video in the browser.

Open URL


In this article, we explored markdown language to do formatting in a SQL Notebook of Azure Data Studio. I have covered most of the formatting options, and you can combine those for preparing a handbook with better visualization and useful pieces of information.

Rajendra Gupta
Azure Data Studio

About Rajendra Gupta

As an MCSA certified and Microsoft Certified Trainer in Gurgaon, India, with 13 years of experience, Rajendra works for a variety of large companies focusing on performance optimization, monitoring, high availability, and disaster recovery strategies and implementation. He is the author of hundreds of authoritative articles on SQL Server, Azure, MySQL, Linux, Power BI, Performance tuning, AWS/Amazon RDS, Git, and related technologies that have been viewed by over 10m readers to date. He is the creator of one of the biggest free online collections of articles on a single topic, with his 50-part series on SQL Server Always On Availability Groups. Based on his contribution to the SQL Server community, he has been recognized with various awards including the prestigious “Best author of the year" continuously in 2020 and 2021 at SQLShack. Raj is always interested in new challenges so if you need consulting help on any subject covered in his writings, he can be reached at rajendra.gupta16@gmail.com View all posts by Rajendra Gupta