Styling: The Look and Feel#

To effectively convey messages, a good design is indispensable. Even if your content is amazing, if it is presented as just a wall of plain text, chances are that people will not pay a lot of attention to it. Luckily, Jupyter Book has plenty of different options to format text, including media and much more.

On this page, we will review some basic Markdown formatting bits. For a more detailed view, check out markdownguide.com as one of many resources.

Formatting Text#

Let’s start with the fundamentals:

Italic#

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

Syntax

Output

_italic_

italic

*italic*

italic

To make a text bold add “*” before and after the word: *bold*= bold

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

  • Two

    • Sublist

  • Three

    • Sublist

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

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.

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 2

## Heading 2.1

## Heading 2.2

Embedded code#

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

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:

def f(x): return x**2

Writing latex#

Let’s use %%latex to render a block of latex:

Syntax

Output

$$F(k) = \int_{-\infty}^{\infty} f(x) e^{2\pi i k} \mathrm{d} x$$

$\(F(k) = \int_{-\infty}^{\infty} f(x) e^{2\pi i k} \mathrm{d} x\)$

Plotting in the notebook#

Notebooks support a variety of fantastic plotting options, including static and interactive graphics. This magic configures matplotlib to render its figures inline:

%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()

Special Content Blocks - Directives and Roles#

Directives and Roles are somewhat similiar to functions for markup language and allow for specific customizations of the look and feel of your book. Both accept various kinds of inputs, which are explained in further detail below.

Directives#

With directives, you can adjust the look and feel of your Jupyter Book.

Directives are written like this:

```{mydirectivename}
My directive content

Where {mydirectivename}would be the name of the directive. However, this directive does not yet exist. While you can integrate directives, there are many directives already implemented in Jupyter Book. For instance, if you want to add a note, you can use:

```{note}
Here is a note

Which results in:

Note

Here is a note

Roles#

Roles are very similar in usage. However, they are somewhat simpler and are limited to one line.

For example:

Some content {rolename}`and here is my role's content!`

Where {rolename}would be the name of the role.

For instance, if you want to reference another page of your book, you can use the {doc}role:

{doc}`../intro`

results in ../intro

What Roles and Directives are available?#

There is more information on how to use Roles and Directives in Media, feel free to check it out!

For more information on what roles and directives you can use, check out: