Using Markdown for documentation

Markdown is great! All the readmes in the Activities in this module and the site you are reading right now is written using it. A bit of familiarity would be extremely useful for your projects.

The following is based on guides found here and here

A more in depth look can be found on the github documentation but the basics here are more than enough for our needs.

You can quickly check your markdown by pasting it into this site

Table of contents
  1. Using Markdown for documentation
  2. Headings
  3. Text styles
    1. Normal
    2. Bold
    3. Italic
    4. Bold and Italic
    5. Strike-through
  4. Code and Syntax Highlighting
    1. Inline Code
    2. Code block
  5. Lists
    1. Ordered
    2. Unordered
  6. Horizontal Rule
  7. Tables
  8. Links
    1. Inline Links
    2. Reference Links
    3. Relative link
  9. Images
  10. Happy Coding!

Headings

Heading levels set by #

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Will look like this:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Text styles

Normal 

 C programming is my favourite.

C programming is my favourite.

Bold 

**C programming is my favourite.**
__ C programming is my favourite.__

C programming is my favourite.

Italic 

*C programming is my favourite.*
_C programming is my favourite._
  • C programming is my favourite.*

Bold and Italic 

**_ C programming is my favourite._**

C programming is my favourite.

Strike-through 

~~C programming is my favourite..~~

C programming is my favourite.

Code and Syntax Highlighting

Inline Code

You can highlight code in-line text by surrounding the text with back ticks `` (next to the 1 key) which look like this int num = 0.

Code block

Blocks of code are typically fenced by lines with three back-ticks ```, you can specify the language next to the first ticks

```c
int array[5] ={1,2,3,4,5};
float result = 0.0;
```

Will give you the code block with syntax highlighted:

int array[5] ={1,2,3,4,5};
float result = 0.0;

Lists

Ordered 

1. One
2. Two
3. Three
  1. One
  2. Two
  3. Three

Unordered 

- 1
- 2
- 3
  • 1
  • 2
  • 3

Horizontal Rule 

---

Tables

Tables are one of the more complicated things in Markdown!

You can either write it directly in Markdown like this:


| Default    | Left align | Center align | Right align |
| ---------- | :--------- | :----------: | ----------: |
| 9999999999 | 9999999999 | 9999999999   | 9999999999  |
| 999999999  | 999999999  | 999999999    | 999999999   |
Default Left align Center align Right align
9999999999 9999999999 9999999999 9999999999
999999999 999999999 999999999 999999999

or using HTML like this which handles text wrapping better:

<table>
<tr>
<td width="33%">
The quick brown fox jumps over the lazy dog.
</td>
<td width="33%">
The quick brown fox jumps over the lazy dog.
</td>
<td width="33%">
The quick brown fox jumps over the lazy dog.
</td>
</tr>
</table>
The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.

Links

Very useful! There are a number of ways of doing this:

[ELEC2645 Website](https://eee-elec2645.github.io/)

ELEC2645 Website

In the body of the text
[ELEC2645 Website][elec2645web]

Then later in the document you can put the reference 
[elec2645web]: https://eee-elec2645.github.io/

In the body of the text ELEC2645 Website

Then later in the document you can put the []: bit, normally at the bottom so it doesn’t matter if it is rendered or not

[Example of a relative link](assets/images/link.png)

Example of a relative link

Images

Follow the same format as links but we add ! before the brackets, like ![](). The Alt text and title text are optional but encouraged (certainly on Bluesky!).

![Cat as a Service](https://cataas.com/cat "A different cat each time")

Cat as a Service

It is not possible to scale or resize the images using Markdown by itself, but we can easily use a bit of html

<img src="https://cataas.com/cat" width="100" height="100" border="10" alt="A different cat each time"/>

A different cat each time

We can also (over)use .gifs

<img src="https://media.giphy.com/media/qLHzYjlA2FW8g/giphy.gif" alt=An ancient meme which shows my age. />

An ancient meme which shows my age.

Happy Coding!

An An