In Jupyter Book Fundamentals we covered the basics of Jupyter Book structure and writing text content in markdown. However, Jupyter Book can go far beyond basic text formatting and has tools to help you share information with figures, videos, special blocks, interactive elements and advanced cross-referencing. In this lesson we will look at some of these features that elevate your book over a plain-text document.
Directives and roles¶
This lesson will make use of roles and directives. These have a similar syntax, and are used to extend the basic markdown features. The main difference is that roles are written in-line and take a single argument, whereas directives are multi-line containers which may have multiple arguments and options.
Both directives and roles use “fences”, which are either (at least) three colons ::: or backticks ```.
You can use more colons or backticks to nest directives.
The MyST documentation explains the syntax, nesting and the difference between colons and backticks in more detail.
Images and figures¶
The quickest way to include an image is with the Markdown notation  as done below
resulting in
However, this gives us limited options to customize the figure.
We can include more options using the figure directive.
If we want to add a figure to our book, we can use the URL of an external website (as in the figure above). However, this carries the risk that the figure will no longer be visible if it is moved from its location.[1] It is therefore better to have the figure as a local source file where you build the book. We will do this by adding an image file to your git repository.
You can position figures in different places (left / center / right / margin), adjust the size, add a caption, etc.. Check the documentation above and try out the different settings.
Embed a video (from YouTube)¶
We can embed videos hosting platforms like YouTube or Vimeo using the iframe directive. For example, the following code embeds a video about Markdown,
```{iframe} https://www.youtube.com/embed/dhzrlXzYOlU?si=n2U0HSJyotjp-r93
:width: 80%
Purves et al. - Jupyter Book 2 0 – A Next Generation tool for sharing for Computational Content
```resulting in
Purves et al. - Jupyter Book 2 0 – A Next Generation tool for sharing for Computational Content
Displaying code¶
You can display code using Markdown syntax.
```language
code
```for example,
``` python
print("Hello world!")
```renders as,
print("Hello world!")You can also use the code directive which will render the code in a block and has features line line numbers and captions.
Diagrams¶
MyST supports displaying Mermaid diagrams using the mermaid directive.
Mermaid let’s you create a number of different types of diagrams using plain text.
This is a great way to show diagrams in your book, while keeping the source easily editable in version control.
For example, the following directive
```{mermaid}
flowchart LR
Start --> Stop
A1(["Novice"]) --> B1
A2(["I do know"]) --> B2 & B1
B1(["Expert"])
B2(["try"])
A(["Start"]) --> B{"Decision"}
B --> C["Option A"] & D["Option B"]
```Renders as,
Admonitions¶
Admonitions can be used to separate text from the main text and highlight it appropriately. Here are a set of admonitions built in to Myst,
Custom admonitions can also be created in a plugin, but hiding the icon and adding your own icon in the title is a quick way to get a custom look.
Tabs, cards, grids¶
MyST has a number of features for arranging and organising content, you have already seen some of these following these lessons.
Tabs can be used to separate content into different sections that can be viewed by clicking on the tab headers. They are useful when you want to present a set of mutually exclusive options.
:::: {tab-set}
::: {tab-item} Tab 1
Content for Tab 1
:::
::: {tab-item} Tab 2
Content for Tab 2
:::
::::Renders as,
Content for Tab 1
Content for Tab 2
Fetching images from someone else’s site also puts strain on their web server, which they may not appreciate.