Skip to content

Markdown

Markdown is a markup language which can be used to simply and beautifully format text^[1], with a major advantage being that even when it is not rendered, it is easily readable by humans, unlike say, HTML. Another advantage to many in the sciences is that when one is using Jupyter notebooks to program in python, one can use markdown to embed formatted text in the notebook, making the code eminently readable. Indeed, it is for this reason that experimental logbooks are required to be prepared using markdown.

Provided below are some tips and tricks for preparing markdown content, but there are countless excellent resources2 on the web for learning markdown, so you are encourage to look around.

How do I markdown?

Writing markdown is not particularly difficult once one knows the tricks of the trade. Perhaps the biggest step one must take is recognising that difference between a text editor and a program for rendering text. A text editor is simple, for example, Notepad for Windows is a very simple text editor with no frills and allows one to simply write text, and importantly also code. The difference between text and code is that text is designed to be digested by humans, whereas code is to be digested by an interpreter (in essence, the computer). However, in practice when it comes to actually reading and digesting text, the display of text editors is typically visually unappealing and often difficult to read. One solution is to create a text editor which renders text into a better format in real time, such as Microsoft Word, but as anyone who has spent any time with Word, it has limitations when it comes to usability and formatting. In the world of science, especially when it comes to publishing, it is much more convenient to use tools such as markdown or which allow the user to write pseudo-code, where content is written in an editor, and then compiled prior to consumption, where the compiler renders the text, images, and other objects (e.g. code, tables, etc.) to make everything look pretty. The answer to the question "how do I markdown" is thus write pseudo code in an editor of your choice and then compile it. Which editor should you use? Well, free and open-source editors exist online and these can be great for getting a start, or you can write markdown in Jupyter as described elsewhere.

This page

This page has a sole purpose: to serve as a reference page for common markdown functions.

Markdown cheat sheet

The cheat sheet is best viewed on this site, as it shows both the markdown code and rendered outcome, but you can also access the raw markdown or pure rendered form of this cheat sheet on GitHub, or access a Jupyter notebook of the markdown to experiment yourself.

Markdown cheat sheet

Formatting

Headings

Headings are made using the # symbol. By using multiple # symbols, you can create subheadings.

Using headings
# Heading

## Sub Heading

### Sub Sub Heading

#### ..etc..


Heading

Sub Heading

Sub Sub Heading

..etc..

Lists

Unordered lists

Bullet points are created using - or *. Indenting the symbol created sub-lists etc...

Unordered lists
* Something

    - Something else

        - More stuff

- Another thing

  • Something

    • Something else

      • More stuff

  • Another thing

Ordered lists

We make ordered lists using numbers

Ordered lists
1. First thing

    1. Sub thing

        1. Other sub thing

2. Second thing

  1. First thing

    1. Sub thing

      1. Other sub thing

  2. Second thing

Task lists

We can make check-box/task lists using square brackets:

Task lists
- [x] Have first coffee
- [ ] Have second coffee
- [ ] Have third coffee
  • Have first coffee
  • Have second coffee
  • Have third coffee

Text

Emphasis
Text accentuation
We can make text **BOLD** or *italic* using the asterisk.

We can make text BOLD or italic using the asterisk.

Quote blocks

Indented quation blocks can be created using >

Quote blocks
> In the beginning...etc..

In the beginning...etc..

Code

We can also highlight code operations inline by encasing the text using the ` or creating code blocks using ```

Coding
Inline code can be rendered using `code/function/thing` whilst code blocks are created via

```
Code thing
does some stuff
```

Inline code can be rendered using code/function/thing whilst code blocks are created via

Code thing
does some stuff
Accentuation

We can highlight regular text using HTML tags...

Colouring text
<mark>Highlighted Text</mark>

<mark style="background-color: lightgreen">Or in a different color</mark>

<span style="color:orange">Changing text color is a similar process</span>

Highlighted Text

Or in a different color

Changing text color is a similar process

Equations

Typesetting

Rather than typing our equations out like E=mc^2, we can format them using $. We can format them inline with our text using a set of $, or we can make them stand out on the page with a double set $$

Equations
$E=mc^2$ will render an inline equation. Using `$$` will make an equation block:

$$
E=mc^2
$$

will render an inline equation. Using $$ will make an equation block:

Sub- and superscripts

If we want superscripts and subscripts, we can use ^ and _ whilst in math mode, that is, in a $ environment.

Superscripts and subscripts
Subscripts and superscripts are created using $x_2, x^2$. If there are multiple characters in a subscript or superscript, curly braces must be used. For example, compare

$$
x^(7t-3)_(a,b,c)
$$

to

$$
x^{7t-3}_{a,b,c}
$$

Subscripts and superscripts are created using . If there are multiple characters in a subscript or superscript, curly braces must be used. For example, compare

to

Multiline equations

Sometimes it is necessary to format mathematical expressions over multiple lines, and formatting in these situations should be done using the align environment.

Multiline equations
$$
    \begin{align}
        V_{in} & =V_C+V_R \\
        & = \frac{q}{C} + IR
    \end{align}
$$

Special characters

We use the \ a lot to enter math commands...

Special characters and commands
- If we want fractions $\frac{2}{3}$.
- If we want some Greek letters $\alpha, \beta, \mu, \gamma, \Gamma, \eta, \theta, \Theta$
- If we want some basic operations $\times, \div, \nabla, \int, \ln, \log, \ne, \sim, \gtrsim, \lesssim, \gg, \ll, \iff$
- Change the size of an equation with `\small, \large, \Large, \huge, \Huge` e.g.
$$\small{x+2}$$
$$\large{x+2}$$
$$\Large{x+2}$$
$$\huge{x+2}$$
$$\Huge{x+2}$$
  • If we want fractions .
  • If we want some Greek letters
  • If we want some basic operations
  • Change the size of an equation with \small, \large, \Large, \huge, \Huge e.g.

Functionality

Inserting links to stuff on the internet is useful when you want to remember where you got information from. It works using a combination of brackets and parentheses []() with the following syntax [title](link).

Inserting links
[Here](https://en.wikipedia.org/wiki/Cat) is the Wikepedia page about cats

Here is the Wikepedia page about cats

Tables

When constructing tables, you draw the table in using combinations of | and -- as seen here.

Inserting a table
| Thing | Description |
| ----------- | ----------- |
| Header | Title |
| Paragraph | Text |
Thing Description
Header Title
Paragraph Text

Images

Images can be imported via

Place an image
![image](path/to/image.svg)

Adding a caption

Adding captions to images isn't quite as straightforward, but can be done using

Place an image with a caption
<figure>
    <img src="path/to/image.svg">
    <figcaption> Caption </figcaption>
</figure>
Who's a good boi

  1. This entire site is (mostly) written using markdown! ↩

  2. The Markdown Guide is an excellent example ↩

Last update: May 18, 2023