Markdown Extended Syntax

Introduction

The original Markdown syntax, published by John Gruber, added several essential elements for editing documents, but some users were not satisfied.

The extended syntax tries to resolve this dissatisfaction by adding new elements through new markups.

Tables, code blocks, automatic links generation and even footnotes are examples of extending the Markdown basic syntax.

These elements can be activated by installing a plugin for your Markdown processor or even using a small variation of the language.

NOTE: it is quite possible that your Markdown application already has support for the elements presented in this article, so it is worth testing each one of them while following the tutorial.

Flavors of Markdown

Markdown has a few different flavors, in other words, variations of the language basic syntax.

These variations, in addition to supporting basic syntax, add elements that enrich the document editing.

Applications compatible with Markdown will often use one of the languages presented below:

CommonMark

GitHub-flavored Markdown (GFM)

Markdown Extra

R Markdown

MultiMarkdown

Creating tables in Markdown

A table in Markdown can be used to present data comparisons by the user.

To create a table in Markdown we use dashes - and vertical bars | to separate rows and columns.

The first line of the table is where we build the header, separating that line by three or more dashes --- so that the Markdown processor understands the formatting.

The separation of the columns is done by using the vertical bar |, also called pipe by programmers.

Below is an example table:

| Title  | Title   |
| ------- | -------- |
| Text   | Text    |
| Text   | Text    |

The vertical bars | used at the ends of the table are for purely cosmetic purposes, the table can be created without adding the side bars.

Example:

Title  | Title
------- | --------
Text   | Text
Text   | Text

The output rendered in HTML:

The width of the cells, within a Markdown table, can vary.

Example:

| Title | Title |
| --- | ----------- |
| Text | Text |
| Text     | Text |

Generating tables in Markdown automatically

Markdown came to make document editing easier, and creating tables can become a bit more tedious.

The use of vertical bars and dashes may displease some users, so it is interesting that we can automate the process of formatting tables in Markdown.

Step 1 - Open our Markdown editor by clicking here.

Step 2 - Click on the automatic table generation icon to open the options panel.

Step 3 - In the options panel:

1. Enter the number of rows in the table.
2. Set the number of columns in the table.
3. Choose the alignment position of the text within the columns.
4. Click to confirm and generate the table structure.

Step 4 - Fill in the values ​​for each cell.

Alignment

Markdown allows you to align the contents of a table column to the left, right or center.

To align content to the left in a Markdown table, place a colon : before the dashes --- that separate the header line.

Example:

| Fruit  | Vegetables | Vegetables |
| :---    | :----    | :---    |
| cashew    | Cress   | Carrot |
| Apple    | Broccoli | Pea |

Result in HTML:

NOTE: Using the colon to align the text to the left is optional, as the table contents are already aligned in that position by default.

To align the text to the right within the Markdown table, insert the colon : after the dashes --- that separate the header line.

Example:

| Fruit  | Vegetables | Vegetables |
|    ---: |    ----: |    ---: |
| cashew    | Cress   | Carrot |
| Apple    | Broccoli | Pea |

Result in HTML:

To align the contents of the column to the center in a Markdown table, add a colon : before and after the dashes that separate the header line.

Example:

| Fruit  | Vegetables | Vegetables |
|  :---:  |  :----:  |  :---:  |
| cashew    | Cress   | Carrot |
| Apple    | Broccoli | Pea |

Result in HTML:

It is possible to merge the alignment formatting, since it only influences the content inside the column.

Example:

| Fruit  | Vegetables | Vegetables |
| :---    |  :----:  |    ---: |
| cashew    | Cress   | Carrot |
| Apple    | Broccoli | Pea |

Result in HTML:

It is worth noting that the alignment of the dashes --- of the line separating the table headings is irrelevant for the Markdown processor, what will really be taken into account is the position of the colon :.

In the following example the dashes --- are positioned to the left of the column and the alignment still works.

| Fruit  | Vegetables | Vegetables |
| :---    | :----:   | ---:    |
| cashew    | Cress   | Carrot |
| Apple    | Broccoli | Pea |

Result in HTML:

NOTE: The contents of the table header will also be aligned according to the position of the colon.

Formatting text in tables

You can insert some basic elements of Markdown inside a table.

Some allowed formatting are, creation of links, emphasize the content in bold or italics and highlight the text as code, however only the inline code is accepted, that is, when created with the opening and closing of backticks `.

Titles, code blocks, blockquotes, lists, horizontal rules, images and HTML tags do not work.

NOTE: You may find applications that accept the insertion of the elements mentioned above inside a table, but this will harm the portability of your document, since other programs do not support it.

Escaping vertical bars in tables

You already learned that, to separate the columns of the table we use the vertical bar |.

Now, if you want to show that same character as content in a cell, you need to use the HTML encoding: |.

When converting your document to another format, the code | will become a vertical bar |.

Fenced code block

A surrounded code block allows you to create code representations without having to indent the line in four spaces or a tab, in addition, it also allows you to define which programming language the block represents, with this, it is possible to apply the appropriate syntax highlighting.

To create a fenced code block in Markdown, place three backticks ``` before the content and three backticks ``` after the content.

Example:

```
{
  "name": "Robert",
  "surname": "Salles",
  "age": 25
}
```

The rendered output looks like this:

{
  "name": "Robert",
  "surname": "Salles",
  "age": 25
}

NOTE: Some Markdown processors allow you to use tildes ~~~ instead of backticks to form the fenced code block.

See also: How to escape backticks inside a code block.

Syntax highlighting

Many JavaScript libraries are used to highlight code blocks, such as: Prism.js & highlight.js.

They take a specific HTML tag, usually the pre or code tag and apply highlighting based on the syntax of the code block's programming language.

The language syntax is usually defined by the parameter class of tag, for example:

<code class="lang-markdown"></code>

Using the class lang-markdown, the framework will know that the content between code tags should be highlighted according to the Markdown language.

NOTE: The highlighting process can be done automatically, some tools have the ability to detect the programming languages ​​in an automated way, without the need to define the language in the class parameter.

When building the code block using Markdown you can specify the programming language right after the first three opening backticks ```.

Example:

```json
{
  "name": "Robert",
  "surname": "Salles",
  "age": 25
}
```

As in the first line of the block, just after the three opening backticks, json was specified, the code will be highlighted accordingly:

{
  "name": "Robert",
  "surname": "Salles",
  "age": 25
}

NOTE: the code will only be highlighted if you use a JavaScript library that performs this type of task, HTML itself does not highlight the code.

Footnotes

A footnote in Markdown allows the user to create a reference to some concept mentioned in the document.

Typically, these footnotes are placed at the end of the document, but in Markdown you can define them anywhere in the text.

When creating a footnote a superscript number in the form of link will be inserted in the location that you created it, when the user clicks on that link it will be taken directly to the location that contains the reference of the note.

The syntax for creating the footnote is divided into two parts.

The first part represents the number containing the link and is created using square brackets, a caret and an identifier, for example: [^1].

The identifier can contain numbers and letters, but does not accept spaces or tabs.

The second part covers the content of the reference itself, to create it use square brackets, a caret followed by the same identifier (which you created earlier), colon, a blank space and the text, example: [^1]: My footnote.

Here is a simple footnote[^1]. Here is a more elaborate footnote[^bignote].

[^1]: This is the first footnote.

[^bignote]: Here is one with several paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you want.

The rendering in golkie itc looks like this:

Here is a simple footnote¹. Here is a more elaborate footnote².

NOTE: The content of the footer can be placed anywhere in the document except inside other Markdown elements such as tables, lists and code blocks.

NOTE: Footnotes will always be numbered sequentially, regardless of the identifiers you created, a sequence of notes [^35], [^yyyy] and [^102_444], will be rendered as 1, 2 and 3.

Adding ID or Class to Markdown elements

When we create tags in HTML, we can assign them a unique identification and a generic identification through the parameters id and class.

Example:

<h2 id="special-title"></h2> & <p class="bg-blue"></p>

With id we can get a specific reference for a particular element, normally the element's id is unique within the HTML markup.

The parameter class is generic and can be assigned to several elements.

The function of id or class is to allow you to easily recognize these elements through JavaScript or CSS, using this id or this class we can handle properties such as color, size, placement, etc.

To add a id or a class to a Markdown element, open curly braces { just after the element's content, place a # sign to indicate an id or a . to indicate a class, then the identifier itself and, finally, close the braces }.

Examples:

### My title {#identifier}

My paragraph{.my-class}

The HTML looks like this:

<h3 id="identifier">My title</h3>

<p class="my-class">My paragraph</p>

NOTE: Please note that not all Markdown applications support the insertion of parameters id or class, it is always important to consult the program documentation.

Links for ids in Markdown

With the same standard syntax for creating links [](), we can connect a direct reference to a id in the document itself.

Within the parentheses where we place the URL, insert the element's id preceded by the hash sign #.

If the id is in another document, the formatting is similar, however, before identification, place the page URL.

Example:

[Header IDs](https://markdown.net.br/sintaxe-estendida#markdown-title-id)

Definition Lists

A definition list in HTML is represented by the tags dl and dt. This list represents terms and their explanations in a conceptual way.

To create a definition list in Markdown, type the term in one line, press Enter, colon, a blank space and the term definition.

Example:

First term
: This is the definition of the first term.

Second term
: This is a definition of the second term.
: This is another definition of the second term.

The HTML looks like this:

<dl>
  <dt>First term</dt>
  <dd>This is the definition of the first term.</dd>
  <dt>Second term</dt>
  <dd>This is a definition of the second term. </dd>
  <dd>This is another definition of the second term.</dd>
</dl>

It's the result:

First term

This is the definition of the first term.

Second term

This is a definition of the second term.

This is another definition of the second term.

Strikethrough in Markdown

The strikethrough is used to correct an error comparatively, usually followed by correction on the same line.

The strikethrough is nothing more than a format that inserts a horizontal line in the middle of a piece of content.

To apply the strikethrough formatting to a content in Markdown use two tildes ~~ before and after the text.

Markdown is: ~~difficult~~ easy to learn.

And the result is this:

Markdown is: difficult easy to learn.

Task lists in Markdown

A task list in Markdown allows the user to create a sequence of elements with checkboxes to their left using square brackets [].

As we are working with a list, it is necessary to start the line of the element with a dash -.

To mark a task as complete, place an x inside the brackets [x].

- [x] Lorem ipsum dolor sit amet
- [ ] Lorem consectetur adipisicing elit
- [ ] Lorem ut labore et dfolore

The rendered output looks like this:

Inserting Emojis in the Markdown document

Yes, you can insert the famous emoticons directly in the Markdown formatting of your document.

There are two most commonly used ways for the task, copying and pasting the emoji into the content or entering emoji codes.

We will understand better how the two procedures work, but first, click here to open our Markdown editor and test the emojis in real time.

Copying and pasting Emojis in Markdown

Step 1 - Open this page of Emojipedia that contains a smiling emoticon and click on the Copy button.

Step 2 - Go back to our Markdown editor, click on the left panel and press CTRL + V to paste.

NOTE: You can explore Emojipedia to find your favorite emoji, the copy and paste procedure is the same for all of them.

If your Markdown application is compatible, you will see the representation of the emoticon directly in the text.

When converting the Markdown document to HTML or even PDF, the emojis are still represented correctly.

NOTE: If the HTML document is not rendering the emojis the way it should, encode the pages in UTF-8.

Using Emoji access codes

An emoji code is formed by identifying the emoticon surrounded by a colon.

To insert an emoji in Markdown using access code, place the emoticon code in between colons.

Example:

I went camping! :tent: I'll be back soon.

This is so funny! :joy:

The rendered output looks like this:

I went camping! ⛺ I'll be back soon.

This is so funny! 😂

Discovering the Emojis access code

If you don't know the emoji access code, use our Markdown editor to find out.

Step 1 - Click here to open Markeditor.

Step 2 - Click on the Emojis insertion button on the toolbar.

Step 3 - In the Emoji selection window:

1. Choose the source from which you want to get the Emojis.
2. Click on the Emoji that will be inserted in the document (you can click on several Emojis in the same window).
3. Press the confirm button to place the access code for the images in the text.

In the left panel you can see the emoji code and in the right panel the rendering.

NOTE: The images of emoticons can vary greatly from application to application, in this list you find the emojis compatible with Markdown used by GitHub, you can test them in your application to find out if there are compatibility.

Automatic linking URLs in Markdown

Some Markdown processors turn URL into links when they find an address between the less than < and greater than > signs.

Example:

<https://en.markdown.net.br>

On other occasions, embedding the address between <> is not necessary, just insert the URL in the document and the application will automatically convert it.

Example:

https://en.markdown.net.br

The rendered output looks like this:

https://en.markdown.net.br

Disabling automatic URL linking

If you just want to represent a URL in a document and prevent the application from converting it to a link automatically, enclose the address between backticks ``.

`https://en.markdown.net.br`

The rendered output looks like this:

https://en.markdown.net.br

NOTE: It is worth remembering that the use of backticks to surround content transforms it into code.