Markdown basics

Acknowledgements: This page is adapted from health-data-science-OR/jupyterlab-introduction.

1 What is markdown?

Markdown is a way of writing documents using plain text plus a few extra characters to show structure and formatting. Instead of a hidden file format (like a .docx), everything is visible as text: your words and the little symbols (e.g., #, *, -) that control how they look.

When you view or render a Markdown file (for example, by opening it in a preview window or creating a final document), a tool reads your text and these symbols and turns them into a nicely formatted document (for example, HTML or PDF).

A normal Markdown file usually ends in .md. In this workshop we mostly used Quarto Markdown, which is the same idea but with extra features for things like interactivity, code and citations, and those files end in .qmd.

On this page you will practice Markdown features that you can use in your Quarto documents.

2 Headings and subheadings

In Markdown, a heading is formatted with the character #.

The number of # characters represents the level of the heading. For example:

# Heading level 1

## Heading level 2

### Heading level 3

#### Heading level 4

Task: Open markdown.qmd and create three headings:

• A level 1 heading for the page title (for example, # My Markdown Page).
• A level 2 heading called ## Section One.
• A level 3 heading called ### A Smaller Section.

Render the page and check that the heading sizes look different.

3 Adding a horizontal line between sections

To add a horizontal line between sections, use three dashes or asterisk on a line by themselves - either:

---
***

Task: In markdown.qmd:

• Add a horizontal line between two sections (for example, between your Section One and A Smaller Section headings)

Re-render the page to check it has worked.

4 Bold and italic text

To create bold text, you need to surround a word or phrase with **. For example:

The final word of this sentence will be **bold**.

To create italic text, you need to surround a word or phrase with *.

*This whole sentence will be in italics.*

You can also combine both if you need stronger emphasis.

Task: In markdown.qmd:

• Write one short sentence about anything you like (e.g., “I am learning Quarto today”).
• Make one word in the sentence bold.
• Make a different word in the sentence italic.

Re-render the page to see the effect.

5 Bullet points and numbered lists

To create a bullet list, use * or - or + followed by a space and then your text:

* Bullet point 1
* Bullet point 2
* Bullet point 3

Can give more space by having blank lines between items

* Bullet point 1

* Bullet point 2

* Bullet point 3

You can indent with spaces (or tab) to create sub-bullets:

* Bullet point 1
    * Bullet point level 2
        * Bullet point level 3
* Back to level 1

A numbered list is created in a similar way using numbers, letters or Roman numerals, or can use #, will just give deciminal numbers from 1:

1. Numbered point 1
    a. Numbered point level 2 
    b. Numbered point level 2 again
2. Back to level 1

To create a checklist, add [ ] between the bullet and text. You can then click on the boxes to cross them out, or have them already shown as crossed out using [x].

* [ ] First task
* [x] Finished task

Task: In markdown.qmd:

• Create a bullet list of 3 everyday items (e.g., Tea, Coffee, Biscuits).
• Create a numbered list of 3 simple steps (e.g., Open the file, Make a change, Save and render).
• Add a checklist with three tasks, and mark one as already completed (e.g., Read one article, Write one paragraph of notes, Add article to a report).

6 Block quotes

To indent text as a block quote, use > at the start of the line:

> This is indented

You can use this for quotes, highlights, or short notes.

Task: In markdown.qmd:

• Add a short quote using >, for example > Quarto helps me keep my work organised.

7 Links

You can create a link by putting the link text in square brackets and the web address in parentheses:

[University of Exeter](https://www.exeter.ac.uk/)

University of Exeter

If you just paste a URL, you should wrap it in angle brackets to ensure it is clickable:

<https://www.exeter.ac.uk/>

https://www.exeter.ac.uk/

Task: In markdown.qmd:

• Add one link with custom link text.
• Add one bare URL wrapped in < > so that it becomes clickable.

8 Inline code and code blocks

You can show short bits of code or filenames using single backticks. This is good for things like file names, commands, and short code fragments.

Example:

Run `python script.py` in your terminal.

Open `analysis.qmd` and edit the first section.

Run python script.py in your terminal.

Open analysis.qmd and edit the first section.

For longer code, use a code block fenced with three backticks:

```bash
python script.py --help
echo "Hello, world"
```

python script.py --help
echo "Hello, world"

Task: In markdown.qmd:

• Use inline code (single backticks) to show one filename and one command.
• Add a fenced code block with 2-3 lines of example code (any language you like) - or just some text if you are unfamiliar.

9 Tables

You can create simple tables using pipes | and dashes -:

| Letter | Number |
| - | - |
| A | 1 |
| B | 2 |
| C | 3 |

Letter	Number
A	1
B	2
C	3

Task: In markdown.qmd:

• Create a small table with two columns and at least three rows (for example, “Item” and “Quantity”).