Markdown (Cheat sheet) - Jupyter Book 2 Workshop Template

Below is a set of frequently used markdown commands for Jupyter Book 2 made with MyST. A good practice is to download the source file by clicking the download icon at the top right of this page and inspect the code.

Book structure¶

We can distinguish between two structures: that of the book’s content (a collection of different documents), and the (internal) structure of the chapters which consists of content structured in sections and subsections.

Table of Contents¶

In the myst.yml file, you can specify the structure of the book as shown in Program 1. Here you can indicate which files belong to the book and in what order. You can also create dropdown menus in your ToC by including children When not specifying a ToC, all files are automatically included in alphabetical order.

myst.yml

44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
    - file: index.md                      # the landing page
    - file: content/1_intro.md
    - file: content/2_jup_nb.ipynb
    - file: content/3_cheat_sheet.md
    - file: content/lessons/your_turn.md          # dropdown menu
      children:
        - file: content/lessons/0_setup.md
        - file: content/lessons/1_firstedit.md
        - file: content/lessons/2_nextstep.md
          children:
            - file: content/lessons/2a_plugins.md
        - file: content/lessons/reuse.md
        - file: content/lessons/executable.md
        # - file: content/lessons/4_styling.md
        - file: content/lessons/5_workflows.md
        - file: content/lessons/6_pdfoutput.md
    - file: content/advanced_start.md
    - file: content/software.md
    - file: content/gallery.md

Program 1:The Table of Contents (ToC) for this book.

If you have specified a ToC and create a new file, you’ll need to add it to the myst.yml file to include it in the book.

Headings¶

To make sections within a page, use a number of # symbols at the beginning of a line. The more #s increases the level of the heading.

# Heading level 1
## Heading level 2
### Heading level 3

Typically, a page only has a single level 1 heading, the page’s title and higher level headings are used for sections and subsections.

Basic Formatting¶

Markdown is a markup language where text formatting is done with small pieces of code (just like HTML). This is a table with some frequently used formatting options.

Table 1:Some basic Markdown text formatting

Element	Syntax	Example
Bold	`bold text`	Bold
Italic	`italics`	Italics
Emphasis	`*emphasis*`	emphasis
Inline Formula	$F = m \cdot a$	$F = m \cdot a$
Footnote	`- A footnote reference[^myref]` `[^myref]: This is an auto-numbered footnote definition.`	- A footnote reference^[1]

You can create a new line by either a hard enter and a blank line, a \ at the end of the line and enter, or two spaces at the end of the line.

New Lines¶

Generally, in markdown, a single hard enter does not create a new line. You need to use one of the options below.

A new line with double space. A new line with a \.
A new line with a hard enter and blank line.

No new line with just a hard enter and text on the next line. Like this

Mathematics and equations¶

For STEM subjects, mathematical equations and symbol are essential. You can include equations in JupyterBooks using the LaTeX syntax for mathematics.

Labelled equations using double dollars, such as (1), can be referenced.

F_{\mathrm{res}} = m \cdot a

(1)

But you can also write inline equations with single dollars.

$s=v_{\mathrm{avg}}t$

Table 2:Some examples of LaTeX mathematics notation

Name	Syntax	Output
Greek script	`\Delta \lambda`	$\Delta \lambda$
root	`\sqrt{4}`	$\sqrt{4}$
superscript/power	`x^{2a}`	$x^{2a}$
fraction	`\frac{2}{3}`	$\frac{2}{3}$
subscript	`x_{\mathrm{avg}}`	$x_{\mathrm{avg}}$
multiply	`a \cdot b`	$a \cdot b$
derivative	`\frac{\Delta f}{\Delta t}`	$\frac{\Delta f}{\Delta t}$
integral	`\int_a^b f(x) \mathrm{d}x`	$\int_a^b f(x) \mathrm{d}x$
sine	`\sin(x)`	$\sin(x)$

You can read about more of the LaTeX mathematics syntax in the LaTeX wikibook

Lists¶

Ordered lists¶

Ordered lists can be made with automatically numbered items.

item 1
item 2.
item 3.

Or you can manually number the items

item 1
item 2.
item 3.

Unordered lists¶

Unordered lists use - or * for each item.

Checklists¶

You can also create checklists. The checks are interactive, you can tick or untick them.

Create a markdown cheat sheet
Publish online
Let others test

Tables¶

In Markdown, tables are created with the separator |

Header 1	Header 2	Header 3
text 1	text 2	text 3
text 4	text 5	text 6

Using a table directive, like Table 3 lets you add a caption and label so you can reference it.

Table 3:An example table

Header 1	Header 2	Header 3
text 1	text 2	text 3
text 4	text 5	text 6

Blocks¶

Tabs¶

Tab 1

Tab 2

Text in tab 1

Cards¶

header

Title

With some text

Grids¶

Cards can be arranged side by side, with the number of cards shown adapting to different screen sizes from small to large.

With a nice header

And cool text

Also with a nice header

Without cool text

Admonitions¶

You can add special blocks that are highlighted in the text. See, for example, the warning below.

This is a warning without icon

Here is a warning

There are different variants such as:

tip
admonition
warning
note
objective

Using plugins you can add your own custom admonitions:

Exercises¶

A special case is the exercises which can be labelled and can come with a solution that is linked to the exercise:

Solution to Exercise 1

Figures¶

A site/book naturally needs figures. There are roughly two ways to add a figure:

Quick figure, without formatting options

![](path/to/figure)

Better way with more control:

Here we used figures hosted online, but you can also add figures to a folder (e.g., called figures), and then use a relative path (e.g. ../figures/sunset.png).

YouTube¶

To embed YouTube videos on the site, you need the embed YT link. The code is then:

A super fun video from the project Show the Physics

```{iframe} https://www.youtube.com/embed/YDBr1Lof_mI?si=thWYK9MFi5QJv-tW
:width: 80%
:align: center

A super fun video from the project [Show the Physics](https://interactivetextbooks.tudelft.nl/showthephysics)
```

References & Links¶

You can include links like this. With the markdown syntax: [text](link). link can take a number of forms including,

A URL
A label prepended with a # (like in the examples of figures and equations here)
A references to an external MyST project, using xref:
A wikipedia page, using wiki:
A DOI, using doi:

MyST lets you add labels to any block of content by adding a label like (label)= before the block. This is a great way to reference things like sections or paragraphs, which don’t otherwise have a label like figure directives or equations.

If you leave the text empty, appropriate link text will be automatically generated. When referencing objects with a name or number, you can use {name} and {number} (or %s) in text to use the name and number in the link text respectively.

Below are a few examples of references,

This is a hyperlink
This is a reference to equation (1)
This is a reference to a table Table 3 or Tab. 3
This is a reference to a figure Figure 1 or Fig. With a nice caption
This is a reference to an external MyST project External MyST projects
This is a reference to a DOI Pols (2021) or Pols (2021)
This is a reference to a Wikipedia page Project Jupyter
This is a reference to a GitHub pull request jupyter-book/mystmd#2106
This is a reference to a file in GitHub README.md

- This is a [hyperlink](https://nos.nl)
- This is a reference to equation [](#eq_newton)
- This is a reference to a table [](#tl_example) or [Tab. %s](#tl_example)
- This is a reference to a figure [](#fig_sunset) or [**Fig. {name}**](#fig_sunset)
- This is a reference to an external MyST project [](xref:myst-guide/external-references#myst-xref)
- This is a reference to a DOI [](https://doi.org/10.1088/1361-6552/abf208) or [](doi:10.1088/1361-6552/abf208)
- This is a reference to a Wikipedia page [](wiki:Project_Jupyter)
- This is a reference to a GitHub pull request [](https://github.com/jupyter-book/mystmd/pull/2106)
- This is a reference to a file in GitHub [](https://github.com/jupyter-book/mystmd/blob/d39d9d68b2d67002771d95a87b56334d2d853585/README.md?#L1-L5)

Citations¶

You can cite entries in a Bibtex bibliography using @. The bibliography file is named reference.bib and located at the project’s root directory.

Feynman et al. (1965)
Feynman et al. (1965, p. 750)

Footnotes¶

This is an auto-numbered footnote definition.
↩

References¶

Pols, F. (2021). What’s inside the pink box? A nature of science activity for teachers and students. Physics Education, 56(4), 045004. 10.1088/1361-6552/abf208
Feynman, R. P., Leighton, R. B., Sands, M., & Hafner, E. M. (1965). The feynman lectures on physics; vol. i. American Journal of Physics, 33(9), 750–752.

Jupyter Book 2 Workshop Template

Markdown & Jupyter Notebook

Jupyter Book 2 Workshop Template

Create your first Jupyter Book 2