Markdown

Markdown is a markup language which is quite similar to plain text. This makes it possible to write pretty nice text documents which also can be rendered by a markdown reader. Markdown is also designed to be converted to HTML for a nicer look. The HTML rendering will differ depending on what tool is rendering the markdown source. On this page Jekyll is used to create the HTML.

Syntax

Text

Text is just written normally. To start a new paragraph add one empty line in the markdown text.

This markdown text has two
lines separated with a newline

Will render like this::

This markdown text has two lines separated with a newline

I.e. the newline is not shown in the rendered result.

Paragraphs are created with an empty line.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim 
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex 
ea commodo consequat.
   
Duis aute irure dolor in reprehenderit in voluptate 
velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat 
cupidatat non proident, sunt in culpa qui officia deserunt mollit 
anim id est laborum.

Renders as:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Headings

Headers are written using #, and the number of # defines the header level.

First level header

is written like this

# First level header

Second level header

## Second level header

Third level header

### Third level header

Fourth level header

#### Fourth level header

Fifth level header

##### Fifth level header

The actual formatting when showed as html (like in this note) can of course be controlled with html styles (css).

Formatting

Bold text is written with double * before and after text

**Bold text**

Italic text is written with single * before and after the text

*Italic text*

You can also use underscores _ instead of *

Strike through is written by adding ~~ before and after text

~~Strike through~~

Code

Code is written by indenting the text. An example:

for (const auto& a : vec)
{
  std::cout << a << std::endl;
}

Code can also be marked by three backticks

```c++
for (const auto& a : vec)
{
  std::cout << a << std::endl;
}
```

This method also allows to specify syntax highlighting, in the example above I want c++ syntax highlight. The result is:

for (const auto& a : vec)
{
  std::cout << a << std::endl;
}

Inside a code snipped other formatting is not possible, e.g. you cannot add ** for bold text.

Quotes

Quotes can be inserted with ‘greater than’ >

> This is a quote

This is a quote

And can be nested to have a qoute in a qoute:

> Quoting a quote
> > First quote

Quoting a quote

First quote

Links

There are two kinds of links.

Inline links which is perfect when the text is rendered in a markdown reader as HTML. Reference links are a bit more readable in the markdown document itself as a text file.

The text with the link is surrounded with square brackets, the url is written in paranteses after the brackets. Like the following example

Create a link like [this](https://www.hjortsberg.org)

With the result:

Create a link like this

To create a reference link the text only contains an id and futher down there is a reference “table” with the links.

A reference link like [this][1] with a table later in the [document][2]

[1]: https://hjortsberg.org
[2]: https://hjortsberg.org/notes/ "My notes"

With this result:

A reference link like this with a table later in the document

Note that a title can be given in double quotes after the url which will appear as a textbox when hovering the mouse over the link.

It is common to render markdown as HTML and then one might want to link to a section in the same document. A header will be a HTML tag with an id so you can create a link to a section like this

   Link to section [Links](#links)

With the result:

Link to section Links

The id is created by the renderer so the exact syntax might depend on renderer. The example works for Jekyll.

Images

An image can be shown with

![alt attribute][3]

[3]: /images/mdnote.jpg "Example image"

Example:

Or with a single line

Single line image ![Alt attribute](/images/dontpanic-small.png)

Example:

Single line image

It is not possible to scale the image using this technique. To scale a large image you can embed HTML into the markdown document, see Embed HTML further down.

Lists

Create an unordered bullet list with ‘-‘ or ‘+’ in front of the items.

- item 1
- item 2
+ item 3

Result:

• item 1
• item 2
• item 3

An ordered list with numbers. Note that you can use autonumbering to avoid numbering errors, this looks weird in the plain text markdown document though. The list will also be intended

1. Item1

   Item text

1. Item2
1. Item3

Result:

1. Item1

   Item text

2. Item2
3. Item3

Tables

Tables are a bit harder, they can look better in the markdown document than in the rendered result. A table in markdown is written as in the following example:

|Year | Price | Amount |
|----:|:-----:|--------|
|2000 | $35.4 | 1330   |
|2001 | $44.1 | 1540   |
|2002 | $48.1 | 1610   |

The colons control the alignment for the column, a colon to the right will right align, a colon on both right and left will center align. Default is left aligned. The dashes separating column title from column data need to be at least 3.

I have not configured any css for tables and my Jekyll does no good job in rendering the table, this is the result

Horizontal line

With 3 dashes, asterisks or underscores you can divide texts with a divider.

***

___

Embed HTML

It is also possible to embed HTML into markdown. This can be handy when you want to add things that are not well supported by markdown. For example nicer tables and scaling images. Just write the HTML in your document, e.g. to scale an image:

<img src="/images/bjorn.jpg" height="100" />

Which results in the same image as above scaled to 100 pixel height:

Wrap up

That’s pretty much it. There’s more stuff in markdown but with these basics you will be able to do pretty much.