Document using Markdown¶

Wikipedia - Markdown is a simple text based protocol that lets you generate structured information using any text editor. Using a static site generator, like MKDocs, it’s very easy document to a static website using markdown. Even without a site generator, markdown can quite easily be read in it’s source form. Markdown is also supported byt GitLab and GitHub to generate HTML pages from any markdown file that is committed. Refer to this markdown reference guide for information on further possibilities.

Structure¶

Basic structure in any page is achieved by using Heading levels

By nesting headings, a hierarchical structure can be achieved.

Links¶

Markdown supports embedding links in the text. Embed a link using the following method:

[words in the text](http://example.com/link)

The words in the text will now link to http://example.com/link.

You can also link to files within the your site by using relative links:

[mkdocs documentation](./mkdocs.md)

will link you to the MKDocs.

Tables¶

Properly formatted, tables in markdown can be easily read from the source code.

|Column header 1|Column header 2|
|---------------|---------------|
|R1,C1          |R1,C2          |
|R2,C1          |R2,C2          |
|R3,C1          |R3,C2          |

Will generate:

When you want to center the content of your cells, format your table using colons, like:

|Column header 1|Column header 2|
|:-------------:|:-------------:|
|R1,C1          |R1,C2          |
|R2,C1          |R2,C2          |
|R3,C1          |R3,C2          |

Images¶

Use lot’s of images in your documentation.

Image formats and sizes¶

Images for web-pages need to abide by the following rules:

• No bigger than 920px in width
• Format as .jpg unless lossless compression is required.
• Reduce compression quality to 80%

Easy formatting of images can be done with:

• Preview (mac, built in OS)
• Irfanview (Windows)
• ImageMagick (Command line, Mac, Windows and Linux)
• gulp (javascript packaging framework)
• webpack (javascript packaging framework)

Embedding Images¶

An image can be embedded in markdown in the following way:

![Alternative text](dog.png)

Image locations¶

The image is located in the same folder as the markdown file. To have an image in another folder, use relative paths to refer to it.

For instance, in the ./images folder, which resides in the same folder as this markdown page you’re reading:

![Alternative text](./images/dog.png)

Or in am images folder, which resides one folder below this page:

![Alternative text](../images/dog.png)

Image descriptions¶

Use tables to attach descriptions to images. You can put an image in the table heading:

|![Doggy](./dog.png)|
|---------------------------|
|An image of a dog          |

This generates a table, containing the images, with a subtext:

An image of a dog

Code¶

Code blocks¶

Code can be displayed in code blocks: a piece of text, surrounded by three backticks.

Backticks can be confused with quotationmarks. You can often find the character on your keyboard on the same key as the tilde (~).

Code Annotations¶

Annotations in code can be placed as numbered comments, with numbers between parens, like // (1) for annotation 1, //(2) for annotation 2, etc. The annotation text will be referenced from an ordered list, placed below the codeblock:

1. Annotation 1
2. Annotation 2

Example:

```javascript
class Ball { //(1)
    constructor(){
        this.position = {x:100, y:100} //(2)
    }
}
```
1. Annotation 1
2. Annotation 2

Becomes:

class Ball { //(1)
    constructor(){
        this.position = {x:100, y:100} //(2)
    }
}

1. Annotation 1
2. Annotation 2

Source: Code annotaties

Icons¶

You can use fontawesome and meterial icons. Which icons you can use, yuou can find on the material documentation site.

• :material-space-invaders: becomes
• :octicons-markdown-16: becomes

Unfortunately, this won’t work in the table of contents

Videos¶

Please don’t embed youtube videos to your documentation page, as these links will die over time, leaving us with partial documentation. Instead, create small (<10MB) videos in mp4 or webm format and embed them using plain HTML:

Upload a video file in the same folder as the markdown file Use the following HTML tag to embed the video:

<video controls poster="video_thumbnail.png"> <source src="hello_world_video_demo.mp4" type="video/mp4"></video>

will result in:

The tag poster="video_thumbnail.png" is not compulsory, but your video may start with a boring thumbnail. Please note that, for this to work, both files must be placed in a folder that has the same name as the markdown file you are embedding the video in. So if I am editing the file markdown.md, the video must be in the folder markdown, which is itself placed in the same folder as the markdown file.

|<video controls poster="video_thumbnail.png"> <source src="hello_world_video_demo.mp4" type="video/mp4"></video>|
|:-:|
|A centered video in a table with subtext|

Keyboard glyphs¶

Keyboard glyphs are great for software manuals and tutorials. The markdown code:

++ctrl+alt+del++

will result in Ctrl+Alt+Del.

Admonitions¶

Markdown details are a nice way to enrich your documentation with more than just text and images. An example of this can be found on this page, such as the “tip” in the video section.

A block containing a tip or a warning or any other kind of counsil is called an admonition. Admonitions can be made in several ways:

!!! static admonition
    A static admonition starts with three exclamation marks. All text that is to bew contained in the admonition will be indented with one tab.

Will result in:

??? Collapsible
    To make the block collapsible, start with question marks instead of exclamation marks.

Will result in:

Some specific words for admonition block will result in specific markup. Supported types can be found here.

Some supported words are:

!!! tip
or
??? tip

!!! warning
or
??? warning

!!! quote
or
??? quote

!!! success
or
??? success

!!! failure
or
??? failure

!!! danger
or
??? danger

!!! bug
or
??? bug

Markdown and VSCode¶

The following VSCode extensions can greatly help in creating documents in markdown using Visual Studio Code.

¶