Markdown based Notebook

Jupyter Book allows Markdown Based Notebooks, these are plain text instead of the json based format of the traditional notebooks (.ipynb). There are some things to keep in mind when using this format as explained below.

There is also a traditional Jupyter version of this chapter.

1Advantages and Disadvantages of Markdown Based Notebooks¶

1.1Advantages¶

• The notebook is plain text, i.e. easier to manipulate, friendlier with git and does not require any special software.

• Load time is faster and can be modified in any text editor.

• Does not require any software to be installed, not even Python, the book can be built in a CI/CD pipeline.

• More resilient to format errors, i.e. if the ipynb is an invalid JSON the whole notebook cannot be rendered.

• It is easier to add tags to code cells, no need for plugins or addons.

• Readers will have the additional option to download the chapter as a markdown file

• Readers can execute code directly on the site with Thebe (this is also possible with ipynb)

1.2Disadvantages¶

• In Markdown notebooks the output for any code cell is not shown before building the notebook.

• The notebook needs to be executed at build time.

• Kernel details should be provide at the top as metadata.

• No actual separation “in cells”, everything is a long text file.

• For local builds using Windows, Python 3.7 should be used - 3.8+ is not yet supported.

• No support for Colab (GPU) or Binder

2Standard Markdown¶

These features are supported by all renderers as they are part of the basic set of features of Markdown. Some examples were extracted from the official docs.

print("Here is a Python cell2")

Here is a Python cell2

2.1Text Formating¶

In a Markdown text one can use bold, italics or both. It is also posible to combine it with monospace.

2.2Quotes¶

It is also possible to quote

2.3Lists¶

To keep everything organize, one usually use lists either ordered

1. Step 1

2. Step 2

3. Step 3

Or without any order

• Requirement 1

• Requirement 2

• Requirement 3

2.4Horizontal Rule¶

Useful to separate sections

From other non-related topic

2.5Links¶

You know that there many search engines online?

There are some which focus on privacy, others just work arround Google and there is also one that uses ecryption!

2.6Images¶

One image is worth a thousand words some say

But it is even better if you can click them

3Limited Support¶

These features are part of some flavours of Markdown but not all renderers can process them. It is recommended to visualize this document in the target platform to check exactly which features are supported

3.1Tables¶

Tables are really complicated in Markdown and should only be generated by a specialized tool. Don’t modify markdown tables manually

3.2Block of Code¶

For code blocks, Jupyter Book will add a Copy button in the top left corner to easily copy all the text in the block.

Some times one wants to share data

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

Or simply say hello

print("Hello World!")

3.3Footnotes¶

Here’s a sentence with a footnote. ^[1]

3.4Math¶

Some renderers can process inline math, $x=2$ and other can also process whole line math

If supported, alignment can be done with array

3.5Not supported in Jupyter Book¶

These are features that some renderers support but are not supported by Jupyter Book

3.5.1Strikethrough¶

Some times you ~~make a mistake~~ have a great idea

However, a HTML approach can produce the desired result

Some times you make a mistake have a great idea

3.5.2Check List¶

• Write the press release

• Update the website

• Contact the media

However, a HTML approach can produce the desired result

[ ] Write the press release

[ ] Update the website

[ ] Contact the media

4MyST Specific¶

These are some features that are the moment are only compatible with Jupyter Book. That means that rendering the notebook in other services (Github, NBviewer, Nteract, Data Lore, etc.) might not work as shown below. If your only target platform is Jupyter Book, you can use any of the following.

4.1Colored Admonitions¶

4.2Hidden Toggles¶

4.3Dropdowns¶

4.4Dropdowns with Admonitions¶

4.5Panels¶

4.6Tabs¶

4.7Sidebars¶

Sidebars are shown in parallel to the main text, but they span inwards from the margins.

4.8Margin Note¶

Margin notes are more discrete, useful for pointing minor details or add extra information.

They span from the margin outwards

4.9Labels¶

Would you like to write homework for your students? Check the dropdowns!

It is always important to provide enough data to support claims!

4.10Equations¶

4.10.1Without Label¶

4.10.2With Label¶

If the equation has a label, it can be then referenced (4)

4.11Citation¶

This project uses numbered citations (IEEE style), enabled by setting numbered_references: true under site.options in myst.yml. Citations can be customized — see the MyST citations guide for details.

MyST supports Pandoc-style citation syntax. With numbered_references enabled, parenthetical citations render as numbers while narrative citations keep the author name in the text.

4.11.1Parenthetical (numbered)¶

Use square brackets around the citation key: [@perez2011python].

This project uses the Python Language 1 to build Jupyter Book 2.

4.11.2Narrative¶

Use the citation key with an at-sign, without brackets: @perez2011python.

Perez et al. (2011) introduced Python as an ecosystem for scientific computing. Jupyter Book is documented in Community (2020).

MyST automatically adds a references section at the bottom of pages that contain citations. When using numbered references together with footnotes, keep in mind that both appear at the bottom of the page and may be numbered in the same sequence.