7  Notes on Markdown

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. (Wikipedia)

Markdown is standardized by CommonMark but there are many variants.

There are several means to convert markdown to other formats. A widely used one is pandoc. A newer, but very common one is Quarto, a successor to R’s knitr package for reproducible science that mixex text and code.

7.1 Pandoc

Pandoc can be found on pandoc.org. Pandoc claims: “If you need to convert files from one markup format into another, pandoc is your swiss-army knife.”

Pandoc can easily convert markdown formatted files to pdf or html.

For ADA compliant pdf, the Journal of Open Source Software uses markdown for paper submissions (with minor adjustments for references) and converts to pdf using ConTeXt, saying

A common method for PDF generation is to go via LaTeX. However, support for tagging – a requirement for accessible PDFs – is not readily available for LaTeX. The current method used ConTeXt, to produce tagged PDF/A-3

The basic command for converting test.md to test.pdf would look like:

pandoc test.md -o test.pdf -t context

7.2 Quarto

One variant is the Markdown supported in Quarto, which is well described on its webpages. Quarto uses pandoc to handle conversions and can output to the three main formats discussed here: PDF, HTML, and MS Word.

We copy a few pieces of the documentation below:

7.2.1 Figures

Figures are created with the syntax:

![caption](elephant.png){fig-alt="A drawing of an elephant."}

Which contains the image a caption and an alt tag for screen readers. Many other options are also available for sizing and alignment.

An alternate syntax that can be used to wrap, say, generated figures is to use the div-block constructs:

::: {#fig-label layout-ncol=2}

... figure code, e.g. ![sub-caption](link){fig-alt="alt tab"} ...

Main caption
:::

7.3 Tables

Tables can be created in a fairly simple manner with “pipe tables”. The example from the documentation:

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

: Demonstration of pipe table syntax

Demonstration of pipe table syntax

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

Tables may also be generated programattically.

7.3.1 Equations

Quarto provides support for Technical writing including equations, citations, cross-references, footnotes, embedded code, and LateX.

LaTeX equations are authored using standard Pandoc markdown syntax, which uses matching dollar signs (one or two) to indicate inline and display math.

7.3.2 Embedded code

Quarto makes the mix of executable computer code with text quite effortless, allowing for reproducible, dynamic documents.

The embedded code can have labels, captions, alt tags, etc.

Embedded code can also have annotations.