Formatting Content With Markdown

In this section, we’ll cover key Markdown formatting basics along with some MyST formatting features. MyST is a markup language inspired by RMarkdown, supported by both .ipynb and .md files in Jupyter Book. It offers advanced formatting options and lets you integrate interactive elements, such as widgets, dropdowns, and code snippets, into your content. For more details, we encourage you to explore the MyST website.

Now, let’s start with the fundamentals.

Headings

You can add headings using Markdown’s syntax by adding # before your heading. You can vary the heading level by increasing the amount of hash signs:

# Heading 1
## Heading 1.1
### Heading 1.1.1

Italic

To make a text italic add _ or * before and after the word:

Syntax	Output
_italic_	italic
*italic*	italic

Bold

To make a text bold add __ or ** before and after the word:

Syntax	Output
__bold__	bold
**bold**	bold

(Nested) Lists

You can build nested itemized or enumerated lists using either * or - before a word:

* One
    - Sublist
        - This
    - Sublist
        - That
        - The other thing

Which results in:

• One

  • Sublist

    • This

  • Sublist

    • That

    • The other thing

You also create numbered lists by using 1. etc. before your point:

1. Here we go
    1. Sublist
    2. Sublist
2. There we go
3. Now this

Which results in:

1. Here we go

   1. Sublist

   2. Sublist

2. There we go

3. Now this

Horizontal Lines

You can add horizontal rules using three underscores ___ resulting in:

---

Blockquotes

To create a blockquote, it is as simple as putting a > before a text.

Here is a blockquote:

> Beautiful is better than ugly.
> Explicit is better than implicit.
> Simple is better than complex.
> Complex is better than complicated.

And it’s formatted like this:

Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated.

Embedded Code

You can embed code meant for illustration instead of execution in Python by adding `` around statements:

`def f(x):`
  `return x**2`

Which results in:

def f(x): return x**2

Since you need to add this line by line, this might ruin your code formatting. Instead, consider using the HTML formatting, adding <code> before and </code> after your code:

<code>
def f(x):
  return x**2
</code>

Which results in:

def f(x): return x**2

Special Content Blocks - Directives and Roles

Directives and Roles are like functions in a markup language, allowing you to customize the look and feel of your Jupyter Book. Below are some common examples:

Directives

Directives let you add special content blocks, such as notes, tips, or warnings.

For example, if you want to add a note, use this format:

```{note}
Here is a note
```

This will display as:

Note

Here is a note

To create a clickable dropdown you can use the {dropdown} directive:

```{dropdown} Title of my dropdown
Here is the content of my dropdown
```

This will display as:

Title of my dropdown

Here is the content of my dropdown

If you want to use dropdown within another directives, use :class: dropdown:

```{tip}
:class: dropdown
Here is a (hidden) tip
```

Result:

Tip

Here is a (hidden) tip

Roles

Roles are inline commands for formatting or referencing content. E.g., you can use the following roles in your book:

• {doc} to link to other pages of your book

• {cite} for citations (see Adding Citations and Bibliographies for more details)

• {abbr} for abbreviations

Examples:

{doc}`../1_github/intro`
{cite}`munafo2017manifesto`
{abbr}`MyST (Markedly Structured Text)`

Which result to:

Getting Started With GitHub

[Munafò et al., 2017]

MyST

Include Links

When adding links, you have several options. Here are the most common methods:

External Links

To link to an external website, use the following format: [text](https://example.com)

Example	[Learn formatting with Markdown](https://www.markdownguide.org/basic-syntax/)
Result	Learn formatting with Markdown

URL in New Tab

If you want the link to be opened in a new tab automatically, your can use the following HTML based format: <a href="https://example.com" target="_blank">text</a>

Example	[Learn formatting with Markdown](https://www.markdownguide.org/basic-syntax/){target="_blank"}
Result	Learn formatting with Markdown.

Linking Another Page In Your Course

If you want to reference another file within your own project, use a relative path: [text](relative_path)

Note

When using relative paths, ../ is a special notation that tells the system to move up one level in the folder structure.

Example	Check the [previous chapter](../2_host/host_website)
Result	Check the previous chapter

This method gives you full flexibility in how you phrase the link text. Alternatively, you can use the {doc} role, as explained above.

Direct URL

You can also display a URL as a clickable link without custom text by using angle brackets < >: <URL>

Example	<https://www.markdownguide.org/basic-syntax/>
Result	https://www.markdownguide.org/basic-syntax/

Plotting in the Notebook

Jupyter Book provides a range of powerful plotting options, including both static and interactive graphics. For more details, check out this guide. Below are some examples of how to implement this using the Python programming language:

%matplotlib inline

import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(0, 2*np.pi, 300)
y = np.sin(x**2)
plt.plot(x, y)
plt.title("A little chirp")
fig = plt.gcf()  # let's keep the figure object around for later...

import plotly.figure_factory as ff

# Add histogram data
x1 = np.random.randn(200) - 2
x2 = np.random.randn(200)
x3 = np.random.randn(200) + 2
x4 = np.random.randn(200) + 4

# Group data together
hist_data = [x1, x2, x3, x4]

group_labels = ['Group 1', 'Group 2', 'Group 3', 'Group 4']

# Create distplot with custom bin_size
fig = ff.create_distplot(hist_data, group_labels, bin_size=.2)
fig.show()

Practice Time: Modify Your Course Info

How about a quick exercise to put your new skills to the test?

Head over to the README.md file, click on the edit button, and start replacing the placeholder text with your own information. Get creative with headings, bold/italic text, and lists to make it look great. Don’t forget to include the link to your course website so others can easily access it! And be sure to keep the credit for the original G0RELLA template lectures.

Let’s get started!

---

Next Section:

In the next section, you will learn how to embed images, videos, and slides.