The Simplified Guide to Markdown Syntax (with Examples)

A Markdown file is a simple text file containing an easy and quick-to-write syntax for creating "rich" content with links, images, quotes, etc…

Then, depending on the software used, this file is generally transformed and displayed as a classic web page.

The syntax

Unlike other document or data representation languages, in Markdown, line breaks and tabs have meaning, which you will discover throughout this guide.

Text

It is possible to use many different text styles, but there are four things you won't be able to change:

• color
• alignment
• font
• size

Headings

As in HTML, there are 6 levels of headings, which are structured like this:

# Titre 1
## Titre 2
...
###### Titre 6

Be careful, you must always add a space between "#" and the text!

Paragraphs

To create a new paragraph, you simply need to leave an empty line between two portions of text:

Je suis un premier paragraphe

Je suis un deuxième paragraphe

If you simply go to a new line, your text will be added to the current paragraph…

Links

The syntax for links is as follows:

[Texte du lien](https://example.com)

It is very similar to the image syntax we'll see later, be careful not to confuse them

Text styles

To highlight specific information, you simply need to wrap the desired text with the following characters:

_italique_
**gras**
**_gras/italique_**
~~barré~~

Be careful not to insert a space (e.g.: ** gras **), otherwise the styles won't be detected

Quotes

A quote must be preceded by the ">" sign:

> Je suis une citation

Some interpreters even allow you to nest several quotes by skipping a line and adding a tab.

Lists

Unordered list

With the possibility of creating "sub-lists," by adding a tab (or 4 spaces):

* Un élément
* Un autre élément
  * Un élément enfant
  * Un deuxième élément enfant
* Encore un

Always keep a space between the "*" sign and the item's text!

Ordered list

1. Un premier élément
2. Un deuxième élément
3. Un troisième élément
    1. Un premier sous-élément
    2. Un deuxième sous-élément

Note that it is not possible to mark sub-list items as "a." or even "1a.", but only with numbers like the main list.

Images

For an image, in addition to the URL, you can specify alternative text (except for pure illustration images), and you can also specify a title:

Version simple :
![](https://example.com/image.jpg)

Version complète :
![Texte alternatif](https://example.com/image.jpg "Le titre de mon image")

The title will only appear when hovering over the image (except on mobile)

It is also possible to create a clickable image by wrapping an "image" block with a "link" block.

Tables

By creating a table with the "|" and "-" signs, a full table will be recreated in HTML:

| Janvier | Février | Mars | Avril |
|---------|---------|------|-------|
|  1200$  |  7000$  | 430$ |  120$ |

Note that alignment doesn't matter, but it remains easier to read for the person editing the file!

Code blocks

There are two distinct code blocks, the first which is inserted within text:

Je suis un exemple de code `console.log("Hello world")` inséré dans du texte.

Or with an independent block:

```js
const str = "Hello World"
console.log(str);
```

The language is not mandatory, but it can activate syntax highlighting if the interpreter allows it!

An example of a Markdown file

Here is an example of a basic file for a recipe, so you can see all the elements put together!

![Photos de crêpes](https://crepes.com/image.jpg)

# Recette de la pâte à crêpes

Tiré de la *fameuse recette* disponible sur [Internet](https://crepes.com/recette)

## Ingrédients

* Des œufs
* De la farine
* Du lait
* Du sucre
* ~~De l'huile de coude~~

> N'hésitez pas à faire **moitié-moitié** avec du sucre vanillé pour plus de goût !

### Tableau des quantités

| œufs | farine | lait | sucre |
|-------|--------|------|-------|
|   3   |  300g  | 60cl |  20g  |

## Étapes

1. Mettre la farine
2. Ajouter les œufs, le sucre, l'huile et le beurre
3. Mélanger délicatement
4. Faire cuire les crêpes une par une dans une poêle légère

## Partager

Pour intégrer cette recette sur votre site web, vous pouvez copier-coller le code suivante :
```html
<iframe href="https://crepes.com/recette?embed"></iframe>
```

Going further

Comments

Comments are elements that appear in your Markdown file, but not in the final rendering.

There is no official solution, but one of the most compatible syntaxes is the following:

(ligne vide)
[comment]: # (Mon commentaire)

HTML elements

By default, markdown is supposed to be compatible with HTML syntax, for example, it is (theoretically) possible to do this:

![Texte alternatif](https://example.com/image.jpg "Titre de l'image")
ou
<img src="https://example.com/image.jpg" alt="Texte alternatif" title="Titre de l'image"/>

But it doesn't always work!

Some interpreters deliberately ignore HTML tags, or ignore a specific part of them (iframes for example).

Specific implementations

Some software/platforms add elements to the basic Markdown syntax, this is the case for example with GitHub, which implements a "checkbox" system in list form:

- [X] Add CriticMarkup support
- [ ] Add task list support
- [ ] Add Footnotes support

If you're looking for the many implementations and their differences, here is a page that summarizes all of this