Markdown is a markup language with simple syntax. It allows writing in an easy-to-read format before converting it to HTML.

Here is a list of software I use markdown with, to give you an idea of where it can be used: Jekyll (like in this post), GitHub (README.md files), Obsidian (for taking notes), and Stack Overflow (posting with nice format).

In this tutorial I share the markdown syntax I usually use. This is not an extensive list, but a summary of the basic features that you could find useful when starting.

The examples in each section below will have this text color.

Headers

First let’s learn how to write headers. You can do it by adding one or more # before the header text. The more hash symbols, the lower the hierarchy of the header.

## Header 2 
### Header 3
#### Header 4
##### Header 5 
###### Header 6

Header 2

Header 3

Header 4

Header 5
Header 6

For links to other pages or sites, wrap the text to be clicked in square brackets [], and write the URL wrapped in parenthesis () immediately after.

To visit GitHub [click here](https://github.com/).

To visit GitHub click here.

If the link is to another page inside the same static site, you can use relative paths inside the parenthesis.

Lists

Use hyphens for unordered lists.

- First item.
- Second item.
  • First item.
  • Second item.

Use numbers followed by a period for ordered lists.

1. First item.
2. Second item.
  1. First item.
  2. Second item.

Blockquotes

Now we jump into blockquotes. You can use > at the start of a paragraph for adding a blockquote. You don’t need to use it exclusively for quotes. Sometimes a blockquote can emphasize the importance of a phrase or concept.

> And here you would write some very important text. As you can see, 
if you continue writing on the next line, the text still
belongs to the blockquote.

And here you would write some very important text. As you can see, if you continue writing on the next line, the text still belongs to the blockquote.

Bold and Italics

For italics, wrap your text in one * before and after.

For bold, wrap your text in two * before and after.

Then, one asterisk gives you *italics*.
And two asterisks gives you **bold**.
Then, one asterisk gives you italics.
And two asterisks gives you bold.

Code

To create a span of code in a paragraph, wrap the code in backtick quotes.

In a paragraph you can have some code `print("Hello!")`, and more text.

In a paragraph you can have some code print("Hello!"), and more text.

If you want to create a fenced code block (or multi-line code block), wrap the code in triple backtick quotes.

```
print("Hello!")
print("Have a nice day!")
```
print("Hello!")
print("Have a nice day!")

You can add syntax highlighting by specifying the language of your code after the first triple backtick.

```python
print("Hello!")
print("Have a nice day!")
```
print("Hello!")
print("Have a nice day!")

HTML when needed

You can use HTML in markdown files when needed. As an example, for the first version of this tutorial I added a style element:

<style>
    .example {
        color: #d59a61;
    }
</style>

Sources

As mentioned at the beggining, this was an introduction to markdown syntax, based on the tools I use the most. Find more about markdown in the links below: