Content in MarkDown

1. Content in MarkDown#

1.1. Basic text#

The simplest content one can put in a book is plain text. Sections containing only text and images can be incorporated in Jupyter books through MarkDown files. MarkDown files are plain text files with a few extra’s. These extra’s include (demonstrated where feasible):

  • (sub)section headers,

  • hyperlinks,

  • bulleted and numbered lists,

  • bold and italic text,

  • footnotes[1],

  • block quotes,

  • inline images (e.g. the MarkDown logo below).

Image

Many modern plain text editors have a MarkDown writing mode; there are also editors with a split screen setting that allow you to see your text with MarkDown codes and the final result side by side.

The basic version of MarkDown used in Jupyter Books is specified at CommonMark; they offer an overview of the basic options.

1.2. MyST#

Sometimes plain text is all you need. But you may want more. In particular, you may want to break up long pieces of text not just with subsections, but with blocks containing tips, notes, exercises, or background information. And you may want to create internal references to allow your readers to jump quickly to a given section. Therefore, Jupyter books uses an extension of MarkDown called MyST (Markedly Structured Text).

Creating a note (or exercise, tip, or any other block) in MyST is easy.

Note

This is a note

Most ‘what you see is what you get’ MarkDown editors will not recognize the code block, but it will be recognized by the Jupyter book software that generates your website. The VSCode editor with MyST Markdown extension does recognize and preview-render various MyST features, and is my editor of choice, also because it supports many other languages and has integrated version control with git.

Tip

To see how I made this tip, download the MarkDown file using the link at the top right of the page.

Warning

Too many special blocks may make your book unreadable.

1.3. HTML#

As the pages of our book will eventually become webpages, it stands to reason that HTML directives will be recognized, and they are. I advise against their use, unless you have no alternative, as it makes converting your text to a nicely formatted printed version harder. One example I have found useful is the non-breaking space; the HTML command for that is  , which also allows me to show how you prevent text from being parsed. I’ve put a non-breaking space between ‘HTML’ and ‘command’ on the previous line; they should stay together no matter what you do to the browser window. It’s not hard to remember the command: the letters simply make up ‘non-breaking space’.

1.4. Equations#

The extended version of MarkDown that we use for our Jupyter books allows us to incorporate \(\LaTeX\). All the standard LaTeX features are available, such as inline symbols (\(x\)) and equations

(1.1)#\[ \phi(a \bm{v} + b \bm{w}) = a \phi(\bm{v}) + b \phi(\bm{w}). \]

The number of equation (1.1) is not a MarkDown feature; if you look at this page in a MarkDown ‘what you see is what you get’ editor, you’ll see the label I used to refer to it.

Multiple equations can be aligned nicely. Unfortunately, unlike in LaTeX, we can’t give these equations separate numbers, but they can have a joint number:

(1.2)#\[\begin{split} \begin{align*} a &= b \\ c &= d \end{align*} \end{split}\]

Typesetting matrix equations also works just like in LaTeX, for example

\[\begin{split} \begin{pmatrix} 1 & 1 \\ 1 & -1\end{pmatrix} \begin{pmatrix} 1 \\ 1\end{pmatrix} = \begin{pmatrix} 2 \\ 0 \end{pmatrix}. \end{split}\]

We can also combine LaTeX with blocks again, for instance to highlight a theorem:

Theorem 1.1 (Riesz Lemma)

For a vector space \(V\) with an inner product \(\langle\cdot \,, \cdot\rangle\) defined on it, the collection of one-forms defined by \(\phi_{\bm{u}}(\cdot) = \langle\bm{u} \,, \cdot\rangle\) for \(\bm{u} \in V\) gives the complete dual space \(V^*\) of one-forms on \(V\).

1.5. Figures and tables#

While figures and tables can be included directly in MarkDown, it is better to include them using blocks, as these allow us to include captions and references. Figures can be both bitmap and vector images; when available, vector images are recommended, as they are scale-free. For example, Fig. 1.1 shows an SVG image.

../_images/Cell_membrane_detailed_diagram_en.svg

Fig. 1.1 Cartoon of the plasma membrane of a cell, consisting of a bilayer of lipids with a large number of embedded and associated proteins. On the intracellular side, the plasma membrane is supported by the cytoskeleton. On the extracellular side, it can face an extracellular fluid or extracellular tissue. Image created by Mariana Ruiz, obtained from Wikimedia Commons, public domain.#

We can also include tables, as shown in Table 1.1.

Table 1.1 Second moment of the area for some common cross-sectional shapes.#

Shape

Second moment of the area

Massive cylinder, radius \(R\)

\(\frac{\pi}{4} R^4\)

Hollow cylinder, radius \(R\), thickness \(d\)

\(\pi R^3 d\)

Massive square, side \(a\)

\(\frac{1}{12} a^4\)

1.6. References#

What is a good scientific text without references? So let’s cite a paper [1] and a book [2].

NB: The use of a bibliography requires the use of the docutils package, but not every version is compatible with jupyter-book. The error is a bug in docutils 0.18 and 0.19. Unfortunately, the recommended version 0.17.1 does not run smoothly if you use the latest version of python (3.12 or higher), and the newer version 0.20 doesn’t work (yet) with JupyterBook. With python 3.12, there’s a fix: use docutils 0.18.1, and put an extra <div> before the bibliography (see the source file of this document), as that fixes the bug.

[1]

Royce KP Zia, Edward F Redish, and Susan R McKay. Making sense of the Legendre transform. American Journal of Physics, 77(7):614–622, 2009.

[2]

N.G. van Kampen. Stochastic Processes in Physics and Chemistry. North-Holland Personal Library. Elsevier, Amsterdam, third edition, 2007. doi:10.1016/B978-044452965-7/50004-0.