Writing in Markdown and LaTeX

When writing technical and scientific documentation, or when we want to write formatted text in a simple format, we use Markdown and LaTeX. These are plaintext-based languages with specialized syntax to create rich text, graphics, and mathematical equations.

Introduction to Markdown¶

Markdown is a lightweight plaintext-based markup language that uses a simple syntax to create formatted text. Markdown files usually have the .md or .markdown file extension and are used for everything from typesetting papers to blog articles to even this Handbook itself!

Headings¶

Create a heading by adding a number of number signs (#) equal to the heading level to the beginning of the line. To create a level 3 heading with the text “My Level 3 Header” you should write ### My Level 3 Header

Another way to create a level 1 or 2 heading is to add any number of = characters or - characters to the line right after, which creates a level 1 and 2 heading respectively.

Paragraphs¶

To create paragraphs, type the the text directly. Use blank lines to separate one or more lines.

Line Breaks¶

In Markdown, you create a line break by ending a line with two or more spaces and then hitting return.

Emphasis¶

In markdown, you can make text bold or italic or both bold and italic!

To make text bold, add two underscores before and after the word or phrase, or two asterisks before and after the word or phrase. That is, use the syntax **bold text** or __bold text__ to create bold text.

To make a word or phrase italicized, add one asterisk before and after the phrase, or one underscore before and after the phrase. That is, use the syntax *italic text* or _italic text_.

To both bold and italicize text, add three asterisks before and after the word or phrase, or three underscores before and after the word or phrase. That is, use the syntax ***bold and italics*** or ___bold and italics___.

Blockquotes¶

Add > in front of a paragraph to make it a blockquote. For instance, the following syntax:

> "This is a quote!"

Results in the following result:

“This is a quote!”

For blockquotes with multiple paragraphs, add a > on the blank lines between paragraphs. To nest a blockquote, add >> in front of the paragraph to be nested.

Some other Markdown elements can be used in blockquotes. Which ones depends on the Markdown application used.

Lists¶

There are two kinds of lists, ordered and unordered lists, which have different formatting syntax.

Ordered Lists¶

To create a ordered list, add line numbers followed by periods at the beginning of the line. The numbers don’t need to be in numerical order, but they should start with the number one (though they don’t have to). For instance, the following syntax:

1. Apples
2. Pears
3. Oranges

Results in the following rendered result:

1. Apples

2. Pears

3. Oranges

Unordered Lists¶

To create an unordered lists, put dashes, asterisks, or plus signs at the beginning of each item. Indent items to create nested lists. For instance, any of the following syntaxes are valid:

- Apples
- Pears
- Oranges

* Apples
* Pears
* Oranges

+ Apples
+ Pears
+ Oranges

Which all render as follows:

• Apples

• Pears

• Oranges

If you need to start a list with a number followed by a period, use a backslash \\ character to escape the period.

To add an element in between two list elements without interrupting the list, indent the the element with 4 spaces or 1 tab.

Code snippets¶

To create a code snippet, enclose the word or phrase in backticks (`). If your word or phrase you want to denote as a code snippet contains one or more backticks, you can escape the backticks inside by enclosing the word or phrase in double backticks (``) instead of single backticks. For instance, `code` renders as code.

To create a code block, indent every line by 1 tab or four spaces, or use the following syntax:

```
#include <stdio.h>

int main(void)
{
  printf("Hello World\n");
  return 0;
}
```

Whenever possible, add the programming language of the code that is highlighted after the first 3 backticks, which enables syntax highlighting of the code. For instance, for code in the C++ language, a code block might look like this:

```cpp
#include <iostream>
 
int main()
{
  std::cout << "Hello World!" << std::endl;
  return 0;
}
```

Which renders like this:

#include <iostream>
 
int main()
{
  std::cout << "Hello World!" << std::endl;
  return 0;
}

A partial list of language codes is given below. A full list can be found on this page.

Horizontal Rules¶

To create one, use three or more asterisks (***), dashes (---), or underscores (___) on a line by themselves. The rendered output of all is identical. That is, you can use any of the following syntaxes:

---

***

___

Markdown links¶

To create one, enclose the text of the link in brackets, followed immediately by the URL in parentheses. For instance, the syntax [example website](https://example.com) renders as example website. For a raw link, without any text, use angled brackets; for instance, the syntax <https://example.com> renders as https://example.com. This works for both web links and email addresses; for instance, <person@example.com> renders as person@example.com.

To add a tooltip (a small message that appears when the user hovers over the link) to a link, enclose it in quotation marks after the URL but still in the parentheses. For instance, the syntax [example website](https://example.com "This is an example") renders as example website.

Formatting Links¶

To bold or italicize links, add asterisks before and after the entire thing. To denote them as code, put backticks around the text inside the brackets.

Reference-style Links¶

Reference-style links are a kind of link that stores the URL for the link elsewhere, which makes them easier to read, write, and modify.

The first part of a reference-style link is the text of the link in brackets, followed by another set of brackets which contains the label referring to the URL. You can include a space between these 2 sets of brackets, though it isn’t required. The label is not case sensitive and can include letters, numbers, spaces, and punctuation.

The second part of a reference-style link is made up of three parts:

1. The label in brackets, followed by a colon and at least one space

2. The URL for the link, which can be enclosed in angle brackets.

3. An optional title for the link, which is enclosed in double quotes, single quotes, or parentheses.

The second parts of these links can be placed anywhere in the markdown document. Some people prefer to put it right after the paragraph with the link, while others put all of them at the end of the document (like footnotes).

Images¶

To add an image, add an exclamation mark (!) followed by the alt text (a description of the image) in brackets, and finally a path or URL to the image in parentheses. For instance, the following syntax:

![Description of image](https://picsum.photos/500)

will render as follows:

To add a link to a local image, enclose the Markdown for the image in brackets, then add the link in parentheses. That is, if you have a image in the local path img/my_image.jpg, then you can link to it with ![My image](img/my_image.jpg).

Escaping Characters¶

Use a backslash (\) in front of characters that would otherwise be used to format Markdown to instead display the literal character.

Characters You Can Escape¶

You can use a backslashes to escape backslashes (\), backticks (`), asterisks (*), underscores (_), curly braces ({}), brackets ([]), angle brackets (<>), parentheses (()), pound sign (#), plus sign (+), minus sign / hyphen (-), dot (.), exclamation mark (!), and pipe (|).

HTML¶

Most Markdown applications allow the use of HTML tags in the Markdown text. This can be helpful for changing attributes like the color of text or the width of an image, or to create small text with the <sup> tag.

For security reasons, not all Markdown applications support HTML tags, and some only support a subset of them. If your application does support them, use blank lines to separate block-level HTML elements like <div>, <table>, <pre>, <p> from surrounding content. Additionally, try not to indent the tags, as it can interfere with the formatting. Finally, you can’t use Markdown syntax inside block-level HTML tags.

Mathematics¶

Mathematical typesetting uses the LaTeX language, which we will explain next. Be aware that using mathematics in Markdown is not supported by every Markdown renderer.

Introduction to LaTeX¶

LaTeX is a special system of codes used to write mathematical formulas and equations, commonly used in writing papers and also available in Jupyter notebooks. Learning to use LaTeXto be able to typeset equations is a crucial skill for many scientific and engineering fields. However, it is also famously unintuitive. This is a short guide to try to make things easier.

The basics¶

There are two different basic types of math formatting you can achieve in LaTeX. The first type is called inline formatting and gives you smaller-sized equations (inline equations) that flow inline with text, such as $E = m_0 c^2$. The second type is called block formatting and gives you large equations (block equations) that look like this:

To write inline equations, we put our LaTeX code within single dollar signs $...$. For instance, the code for $x = 1$ is $x = 1$. If you type this into a Jupyter notebook cell (with the dollar signs) and then press Shift + Enter, you’ll be able to see the rendered result! Double-clicking on the cell again shows you the code again, so you can edit later.

To write block equations, we put our LaTeX code within double dollar signs $$...$$. For instance, the code $$x = 1$$ gives you an equation that gets its own line on the page:

Note that you can also put long block equations on several lines to make it more readable. For instance, consider this equation:

Notice that this is a rather long equation and if we write everything in a line it might be quite verbose and hard to read. A better way is to spread out the code (between the double dollar signs) over multiple lines, since newlines don’t matter for LaTeX code by default. You can, for instance, write the LaTeX code like this:

$$
x = 1 + 2 + 3
    + 4 + 5 
    + 6 + 7 
    + 8 + 9 
    + 10
$$

Basic algebra & symbols¶

In LaTeX, most basic symbols (like letters of the alphabet, as well as the arithmetic operations $+, -, /, >, <, =$, and numbers) are typed the same way they look. For instance, just as we have seen, $x = y = z = t = 42$ is just typed $x = y = z = t = 42$ in LaTeX code. However, it is also common to use Greek letters in mathematical equations. LaTeX offers special codes to represent these letters: for instance, $\pi = 3.14159...$ is typed with the code $\pi = 3.14159...$, where \pi is the special code to represent the Greek letter $\pi$. Be aware that LaTeX codes are in general case-sensitive! The following table shows a selection of the symbols used for Greek letters:

In addition, a few symbols commonly used in physics with unusual or stylized forms are shown with their LaTeX codes below:

Powers, subcripts, and superscripts¶

For superscripts, use the ^{...} (caret) symbol; for instance, $x^2$ is typeset as $x^{2}$. For subscripts, use the _{...} (underscore) symbol; for instance, $x_{2}$ is typeset as $x_{2}$. (Note that including the {,} curly braces is not always necessary but it’s usually a good idea to use them). For ellipses ($\dots$), use the \dots command. This, for instance, allows us to write equations like:

Which uses the code:

a_{0} x^{3} + a_{1} x^{2} + a_{2} x + a_{3} + \dots = 0

Fractions and radicals¶

Fractions in LaTeXuse the \frac{...}{...} command, where the numerator is placed between the first set of braces and the denominator is placed between the second set of braces. As an example, the code \frac{1}{2} renders as $\frac{1}{2}$. Since the fraction has 1 in the numerator and 2 in the denominator, we have {1}{2} after \frac (in LaTeX the numerator is always written before the denominator, so \frac{2}{1} would be wrong!). We can write more complicated fractions too, like this:

The LaTeX code corresponding to it is:

Y = \frac{1 + 2 + 7/5}{7(9) + 53 - 25}
      + 3600

Writing a radical (for instance, a square root) is accomplished using one of two ways. The first way is to use the \sqrt{...} command. Thus, \sqrt{2} is rendered as $\sqrt{2}$. For n-th roots, we use the \sqrt[n]{...} command, so \sqrt[n}{2} is rendered as $\sqrt[n]{2}$. If we set $n = 3$ then the code \sqrt[3]{2} is then shown as $\sqrt[3]{2}$.

The other way is to use a fraction as an exponent. For instance, $\sqrt{1 + x}$ can also be written as $(1 + x)^{1/2}$ (in code, (1 + x)^{1/2}) or as $(1 + x)^{\frac{1}{2}}$ (in code, (1 + x)^{\frac{1}{2}}).

Uncertainties and inequalities¶

In many mathematical equations, we aim to describe quantities that are not exactly equal to each other or lie in a particular range of uncertainty. For instance, we might find that a measurement is $1 \pm 0.005$ centimeters. For this, we use specialized LaTeXsymbols, as shown in the below table:

Combining what we’ve seen so far, we can now typeset the quadratic formula in LaTeX code:

The LaTeX code is:

x = \frac{b \pm \sqrt{b^2 - 4ac}}{2a}

Trigonometric and logarithmic functions¶

To go beyond basic algebra with purely polynomials, LaTeXoffers us extensive abilities to typeset transcendental functions, like trigonometric and logarithmic functions, as shown by the table below:

We can now type out the famous Euler’s formula in LaTeX:

With the LaTeX code being:

e^{i\phi} = \cos (\phi) + i \sin (\phi)

It is also possible to write out the inverse trigonometric functions with, for instance, \sin^{-1}(x) for $\sin^{-1}(x)$ (inverse sine) and \cos^{-1}(x) for $\cos^{-1}(x)$ (inverse cosine). The other inverse trigonometric functions are also very similar. The hyperbolic trigonometric functions, used in advanced engineering and physics, can also be typed out in a similar way: \sinh(x) for $\sinh(x)$ (hyperbolic sine), \cosh(x) for $\cosh(x)$ (hyperbolic cosine), \tanh(x) for $\tanh(x)$ (hyperbolic tangent), and so on.

Calculus¶

LaTeXoffers rich support for calculus-based symbols. For instance, the \lim_{...} command allows us to write a limit of a function. For instance, the following code:

\lim_{x \to a} f(x) = f(a)

displays as:

We can also write an infinite sum using the \sum_{...}^{...} command, where the lower bound of the sum is between the first 2 braces and the upper bound is between the second 2 braces. For instance:

\sum_{n = 1}^{30} \frac{1}{n!}

displays as:

We can indeed omit the bounds so we just have:

\sum_n \frac{1}{n!}

which displays as:

Derivatives are generally just written as fractions in LaTeX, for instance:

f'(x) = \frac{df}{dx}

displays as:

Note that for time derivatives like $\dfrac{df}{dt}$ one alternative is to use Newton’s dot notation $\dot f$ and $\ddot f$, which correspond to the codes \dot f and \ddot f.

Integrals, by contrast, use a more specialized notation. The \int_{...}^{...} command creates an integral. If we do not specify the bounds, for instance, with the code \int f(x) dx, we just get:

But if we do specify the bounds, for instance, with the code \int_{a}^{b} f(x) dx, we get:

To write the evaluation bounds of an antiderivative, we use the \bigg command. For instance, the code:

F(x)\bigg|_{a}^{b}

displays as shown:

To notate a partial derivative, we use the $\partial f/\partial x$ symbol rather than $df/dx$, which is notated as $\partial f/\partial x$. Thus we have:

A double integral is denoted \iint, and a triple integral denoted \iiint. They display as follows:

In addition, you can write a closed line integral with \oint, which displays as follows:

The gradient of a function $\nabla f$ is coded as \nabla f, the divergence $\nabla \cdot$ is coded as \nabla \cdot, and the curl $\nabla \times$ is coded as \nabla \times. The Laplacian $\nabla^2$ is written as \nabla^2.

Vectors, arrows, lines, and decorative symbols¶

Much of the rest of LaTeXis figuring out other symbols useful (although not always essential) for typesetting a particular symbol, of which some are shown in the table below:

More information¶

This guide introduces a very small subset of LaTeX. For more information, I suggest visiting the following sites:

1. For a full list of LaTeX codes for symbols, see https://oeis.org/wiki/List_of_LaTeX_mathematical_symbols

2. For a website where you can draw symbols and it tells you the LaTeX code, see https://detexify.kirelabs.org/

3. For a complete, in-depth guide to LaTeX, see the tutorial by Overleaf at https://www.overleaf.com/learn

Note also that copying the contents of any math cell from the free graphing/scientific calculator Desmos (https://desmos.com/calculator) will copy the results in LaTeX code that you can later paste in a Jupyter notebook, so it can be used (in a pinch!) as a visual equation editor that "exports" to LaTeX.