Markdown based Notebook

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.

Advantages and Disadvantages of Markdown Based Notebooks#

Advantages#

  • 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)

Disadvantages#

  • 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

Warning

If the notebook requires external tools for the kernel (e.g. Matlab), the only available format is the Traditional Jupyter (.ipynb)

Warning

If you want support for Binder and / or Colab Execution (e.g. for GPU processing), only Traditional Jupyter (.ipynb) are supported

Standard 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

Text Formating#

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

Quotes#

It is also possible to quote

Lists#

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

Horizontal Rule#

Useful to separate sections

From other non-related topic

Images#

One image is worth a thousand words some say

Alternative text

But it is even better if you can click them

Alternative text

Limited 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

Tables#

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

Syntax

Description

Header

Title

Paragraph

Text

Block 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!")

Footnotes#

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

Math#

Some renderers can process inline math, \(x=2\) and other can also process whole line math

\[ \int_0^\infty \frac{x^3}{e^x-1}\,dx = \frac{\pi^4}{15} \]

If supported, alignment can be done with array

\[\begin{split} \begin{array}{llll} a_{11}& =b_{11}& a_{12}& =b_{12}\\ a_{21}& =b_{21}& a_{22}& =b_{22}+c_{22} \end{array} \end{split}\]

Not supported in Jupyter Book#

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

Strikethrough#

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

Check List#

  • [x] Write the press release

  • [ ] Update the website

  • [ ] Contact the media

However, a HTML approach can produce the desired result




MyST 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.

Colored Admonitions#

Note

Here is a Note

Important

Here is an important

Tip

Here is a Tip

Attention

text Here is an attention

Warning

Here is a Warning

Error

Here is an error

admonition

Here is a custom admonition

Hidden Toggles#

Some hidden toggle content!

Panels#

Tabs#

Margin Note#

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

They span from the margin outwards

Labels#

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

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

Equations#

Without Label#

\[x^2 + y^2 = 1\]

With Label#

(1)#\[x^2 + y^2 = 1\]

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

Citation#

There are two types of citations, by name (similar to APA style) and by number (similar to IEEE style).

Citations can be customized, for more detailed explanations please refer to one of the Jupyter Book docs (here, here or here) and the associated extension docs.

By Name#

This project uses the Python Language [Perez et al., 2011].to build Jupyter Book [Community, 2020]

This will not work unless there is a section called `bibliography``

Bibliography for Names#

There are different styles for the bibliography in this case

Alphanumeric - Sorted by Author, year#
[Com20]

Executable Books Community. Jupyter book. February 2020. URL: https://doi.org/10.5281/zenodo.4539666, doi:10.5281/zenodo.4539666.

[PGH11]

Fernando Perez, Brian E Granger, and John D Hunter. Python: an ecosystem for scientific computing. Computing in Science \\& Engineering, 13(2):13–21, 2011.

Alphanumeric - Sorted by order of appearance#
[PGH11]

Fernando Perez, Brian E Granger, and John D Hunter. Python: an ecosystem for scientific computing. Computing in Science \\& Engineering, 13(2):13–21, 2011.

[Com20]

Executable Books Community. Jupyter book. February 2020. URL: https://doi.org/10.5281/zenodo.4539666, doi:10.5281/zenodo.4539666.

Numeric - Sorted by Author, year#
[1]

Executable Books Community. Jupyter book. February 2020. URL: https://doi.org/10.5281/zenodo.4539666, doi:10.5281/zenodo.4539666.

[2]

Fernando Perez, Brian E Granger, and John D Hunter. Python: an ecosystem for scientific computing. Computing in Science \\& Engineering, 13(2):13–21, 2011.

Numeric - Sorted by order of appearance#
[1]

Fernando Perez, Brian E Granger, and John D Hunter. Python: an ecosystem for scientific computing. Computing in Science \\& Engineering, 13(2):13–21, 2011.

[2]

Executable Books Community. Jupyter book. February 2020. URL: https://doi.org/10.5281/zenodo.4539666, doi:10.5281/zenodo.4539666.

By Number#

This project uses the Python Language [2].to build Jupyter Book [3]

This will not work unless there is a section called footbibliography

For different citation styles, check the official docs

When using footcite and footbibliography, the numbers will be arranged in combination with the footnotes. This could lead to confusion for the reader if this type of references are used in combination with footnotes. To mitigate this issue, a similar result can be achieve using cite and bibliography with the unsrt style.

Bibliography for Numbers#

In this case, there is a single style

Contents