Dyr og Data

Dynamic documents — Markdown

Gavin Simpson

gavin@anivet.au.dk

Aarhus University

Mona Larsen

mona@anivet.au.dk

Aarhus University

Wednesday, 19 August 2026

Markdown

Markdown is a lightweight markup language with plain-text formatting syntax.

Aims to be easy-to-read and easy-to-write

Developed by John Gruber, released 16 years ago (March 19th, 2004)

Original version was a text ➙ HTML conversion tool

Widely used on the web: GitHub, Slack, StackOverflow, Discourse, etc. all use it

Markup

Markdown is a markup language

A markup language is one where the user adds simple syntax (the markup) to plain text documents

The markup is used to indicate the structure of the document (e.g. headings) as well as formatting of text (bold, italics) etc

HTML — Hyper Text Markup Language — is an example of a markup language

Why not use HTML?

HTML is very verbose — often more markup that narrative text

Often difficult for a human to read the source

Markdown flavours

Now many flavours of Markdown

Markdown
MultiMarkdown
Kramdown
GitHub flavour
StackOverflow flavour
Pandoc
Commonmark
…

https://xkcd.com/927/

Markdown Syntax

Inline formatting of text

emphasis/italics *text* or _text_ ➙ text
bold **text** ➙ text
code `text` ➙ text

Links

[link text](https://www.foo.org) ➙ link text
bare links <https://www.foo.org> ➙ https://www.foo.org
bare links need a Pandoc extension to be enabled in quarto

Block level markup

headers
paragraphs
lists
code blocks
block quotes
horizontal rules
tables
math

Headers

Two ways to write headers

Heading
=======

Subheading
----------

# Heading 1

## Heading 2

### Heading 3

With the first style there are only two levels of heading allowed

Paragraphs

Paragraphs are indicated by leaving a blank line between paragraphs of text

#| code-line-numbers: false
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer eu metus eros.
Fusce dictum viverra elit, nec tincidunt arcu tempus sed. Aliquam sodales justo
dolor, eget molestie quam accumsan et.

Sed sagittis in ligula sed pellentesque. Fusce sagittis vel sapien nec porta.
Nullam eleifend neque velit, et dignissim tellus sollicitudin nec. Sed semper
diam nulla, sit amet mattis mi egestas vitae. Nullam convallis bibendum libero,
vel commodo nibh commodo eu. Duis odio purus, cursus a dolor nec, dapibus
efficitur massa.

Nam rutrum pretium odio eu ultricies. Curabitur sollicitudin dictum leo, id
vulputate nibh vulputate ac. Mauris quis leo sit amet nulla venenatis
scelerisque quis eu libero. Nullam vel ipsum ac enim blandit sodales. Duis
augue neque, pharetra ut est at, maximus elementum felis. Aliquam tristique
molestie pretium. Praesent eu sodales augue, vel ultricies sapien. Vivamus
sit amet tempor leo. Nulla facilisi. Suspendisse nec volutpat turpis, et
semper sem. Nam a erat congue turpis pharetra eleifend sollicitudin vel
mauris.

Lists

Bulleted lists

Input:

- item 1
- item 2
- item 3

Output:

item 1
item 2
item 3

Can use *, - or . as the bullet

Ordered lists

Input:

1. item 1
2. item 2
3. item 3

Output:

item 1
item 2
item 3

Code blocks

You can insert code by either wrapping the text in backticks

```
# this is some verbatim text

foo <- bar()
```

Or by indenting lines of code/verbatim text by 4 spaces

    # this is some verbatim text

    foo <- bar()

Note there are better ways to insert R code if you want highlighting

Block quotes

To insert a quotation we use a blockquote, indicated by the > at the start of each line.

> "I thoroughly disapprove of duels. If a man should challenge me, I would
  take him kindly and forgivingly by the hand and lead him to a quiet place
  and kill him."
>
> --- Mark Twain

“I thoroughly disapprove of duels. If a man should challenge me, I would take him kindly and forgivingly by the hand and lead him to a quiet place and kill him.”

— Mark Twain

Tables

Not part of the CommonMark standard, but Pandoc & other flavours add them

But they’re a bit of a pain to typeset

Better to get the data for the table into a data frame in R and then use knitr::kable() to render the table to Markdown for you — kableExtra 📦

Simple tables

  Right     Left     Center     Default
-------     ------ ----------   -------
     12     12        12            12
    123     123       123          123
      1     1          1             1

Tables

Pipe tables

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

Images

Images are inserted using link-like syntax

![..alt-text..](path/to/image.png)

The alternative text ..alt-text.. is used

by screen readers for visually impaired users,
if the image can’t be loaded
to provide better image context & description for search engine crawlers

The path should be a relative path to the image file

.png, .jpg, or .svg are commonly supported formats in browsers but any image type supported in the output document format is OK

Pandoc

Pandoc is a universal document converter

Developed by John MacFarlane

https://pandoc.org/

Developed into a comprehensive & complex piece of software

We won’t interact with it directly — R and quarto 📦

Quarto flavour markdown

quarto uses Pandoc to convert the input document to a rendered file

my-file.md ➙ my-file.pdf
my-file.md ➙ my-file.html
my-file.md ➙ my-file.doc

Pandoc is a document processing tool and has it’s own flavour of Markdown with a number of extensions

Consult the Pandoc manual for what you can do with it

Pandoc markdown

Extra things Pandoc enables include

subscript CO~2~ ➙ CO₂
superscript ^15^N ➙ ¹⁵N
footnotes

A footnote[^1]

[^1]: Footnote text

continuation lists

(@) A list whose numbering

continues after

(@) an interruption

Citations

Blah [@doe99] ➙ Blah (Doe, 1999)
Blah blah [@smith04; @doe99] ➙ Blah (Smith, 2004; Doe, 1999)
as shown in @smith04 ➙ as shown in Smith (2004)
Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1]

Citations

Citations are generally entered using cite keys referenced from a .bib BibTeX or BibLaTeX file

@ARTICLE{Wilkinson2020-sb,
  title     = "Time to reality check the promises of machine learning-powered
               precision medicine",
  author    = "Wilkinson, Jack and Arnold, Kellyn F and Murray, Eleanor J and
               van Smeden, Maarten and Carr, Kareem and Sippy, Rachel and de
               Kamps, Marc and Beam, Andrew and Konigorski, Stefan and Lippert,
               Christoph and Gilthorpe, Mark S and Tennant, Peter W G",
  journal   = "The Lancet Digital Health",
  publisher = "Elsevier",
  month     =  sep,
  year      =  2020,
  issn      = "2589-7500",
  doi       = "10.1016/S2589-7500(20)30200-4"
}

Ideally use a reference manager to produce the BibTeX — Zotero

Here Wilkinson2020-sb is the cite key

Cite as [@Wilkinson2020-sb] or @Wilkinson2020-sb in the text

Quarto

Why Quarto?

Quarto files are intended for three main use case

Communicating to decision makers

Focus is on the results and conclusions in a report, not the code or analysis
Communicating with other data scientists (inc. yourself)

Focus will be on the results & conclusions and how you got there with code!
An environment for doing data science

Use the Quarto file as an electronic notebook to record both what you did and why

Quarto

A quarto document is a plain text file with the extension .qmd

A quarto document comprises

a YAML header (optional)
narrative text
code chunks and inline code