It is possible to store Jupyter notebooks in plain Markdown. This allows youto define a notebook structure entirely using MyST Markdown. For more informationabout MyST Markdown, see MyST Markdown overview.

Notebooks with Markdown can be read in, executed, and cached by Jupyter Book (see Execute and cache your pages for information on how to cache pages). This allows you to store all of your notebook content in a text format that is much nicer for version control software, while still having all the functionality of a Jupyter notebook. @jayarjo, this question was specifically about coloring text in IPython notebooks, which allow markdown text. For the behavior of color in GitHub markdown files, see the following question specifically on that issue. The short answer is that there doesn't seem to currently be a way to specify color for text in GitHub markdown documents.

Notebooks with Markdown can be read in, executed, and cached by Jupyter Book (see Execute and cache your pages for information on how to cache pages).This allows you to store all of your notebook content in a text format that is much nicer for version control software, while still having all the functionality of a Jupyter notebook.

Note

MyST notebooks uses [MyST-NB to convert between ipynb and text files][myst-nb:index].See its documentation for more information.

To see an example of a MyST notebook, you can look atmany of the pages of this documentation.For example, see ../interactive/hiding.md and ../content/layout.md.

Create a MyST notebook with Jupytext¶

The easiest way to create a MyST notebook is to use Jupytext, a toolthat allows for two-way conversion between .ipynb and a variety of text files.

Specify your desired blender version and the path to your blend file within google drive or colab local storage. If you do need more information on parameters etc. Look here: Blender CLI Wiki. Read a Jupyter/IPython notebook file (.ipynb) via jsonlite::fromJSON, convert its code cells to R Markdown code chunks, preserve Markdown cells, and write out the results to an Rmd file.

You can convert an .ipynb file to a MyST notebook with the following command:

A resulting mynotebook.md file will be created.This can then be used as a page in your book.

Important

For full compatibility with myst-parser, it is necessary to use jupytext>=1.6.0.

Ipython Notebook Markdown Color Text

Jupytext can also automatically synchronize an .ipynb file with your Markdown.To do so, use a Jupyter interface such as Jupyter Lab or the classic notebook interfaceand follow the Jupytext instructions for paired notebooks.

Convert a Markdown file into Jupytext MyST Markdown¶

Jupyter Book has a small CLI to provide common functionality for manipulating andcreating MyST Markdown files that synchronize with Jupytext. To add Jupytext syntaxto a Markdown file (that will tell Jupytext it is a MyST Markdown file), run thefollowing command:

If you do not specify --kernel, then the default kernel will be used if there isonly one available. If there are multiple kernels available, you must specify onemanually.

Structure of MyST notebooks¶

Let’s take a look at the structure that Jupytext creates, which you may also useto create a MyST notebook from scratch. First, let’s take a look at a simple MyST notebook:

There are three main sections to notice:

Frontmatter YAML¶

MyST notebooks need special frontmatter YAML to tell Jupytext that theycan be converted to .ipynb files. The frontmatter YAML block

tells Jupytext that the file is in myst format, and that its code shouldbe run with a Python 3 kernel.

Code cells¶

Code blocks in MyST notebooks are defined with the following MyST directive:

You can optionally add extra metadata to the code cell, which will be convertedinto cell metadata in the .ipynb file. For example, you can add tags to your codecell like so:

You may also explicitly pass the kernel name after {code-cell} to make it clear whichkernel you are running. For example:

However, remember that there is only one kernel allowed per page.

Markdown content¶

Everything in-between your code cells is parsed as Markdown content using theMyST Markdown parser. See MyST Markdown overview formore information about MyST Markdown.

To explicitly split up Markdown content into two Markdown cells, use the followingpattern:

You may also attach metadata to the cell by adding a Python dictionary after the +++.For example, to add tags to the second cell above:

Warning

Please note that cell breaks and metadata specified in MyST files via the +++ syntaxonly propagate to their .ipynb counterpart. When generating the book’s HTML, Markdowncell information is discarded to avoid conflicting hierarchies in the structure of thedocument. In other words, only code cell tags have an effect on the generated HTML.

Newly added in the 1.0 release of IPython is the nbconvert tool, whichallows you to convert an .ipynb notebook document file into various staticformats.

Currently, nbconvert is provided as a command line tool, run as a scriptusing IPython. A direct export capability from within theIPython Notebook web app is planned.

The command-line syntax to run the nbconvert script is:

This will convert the IPython document file notebook.ipynb into the outputformat given by the FORMAT string.

The default output format is html, for which the --to argument may beomitted:

IPython provides a few templates for some output formats, and these can bespecified via an additional --template argument.

The currently supported export formats are:

• --tohtml

  • --templatefull (default)

    A full static HTML render of the notebook.This looks very similar to the interactive view.

  • --templatebasic

    Simplified HTML, useful for embedding in webpages, blogs, etc.This excludes HTML headers.

• --tolatex

  Latex export. This generates NOTEBOOK_NAME.tex file,ready for export.

  • --templatearticle (default)

    Latex article, derived from Sphinx’s howto template.

  • --templatereport

    Latex report, providing a table of contents and chapters.

  • --templatebasic

    Very basic latex output - mainly meant as a starting point for custom templates.

• --topdf

  Generates a PDF via latex. Supports the same templates as --tolatex.

• --toslides

  This generates a Reveal.js HTML slideshow.It must be served by an HTTP server. The easiest way to do this is adding--postserve on the command-line. The serve post-processor proxiesReveal.js requests to a CDN if no local Reveal.js library is present.To make slides that don’t require an internet connection, just place theReveal.js library in the same directory where your_talk.slides.html is located,or point to another directory using the --reveal-prefix alias.

• --tomarkdown

  Simple markdown output. Markdown cells are unaffected,and code cells indented 4 spaces.

• --torst

  Basic reStructuredText output. Useful as a starting point for embedding notebooksin Sphinx docs.

• --toscript

  Convert a notebook to an executable script.This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook.If there were any magics in an IPython notebook, this may only be executable froman IPython session.

• --tonotebook

  New in version 3.0.

  This doesn’t convert a notebook to a different format per se,instead it allows the running of nbconvert preprocessors on a notebook,and/or conversion to other notebook formats. For example:

  will open the notebook, execute it, capture new output, and save the result inmynotebook.nbconvert.ipynb.

  will create a copy of mynotebook.ipynb in mynotebook.v3.ipynbin version 3 of the notebook format.

  If you want to convert a notebook in-place,you can specify the ouptut file to be the same as the input file:

  Be careful with that, since it will replace the input file.

Note

nbconvert uses pandoc to convert between various markup languages,so pandoc is a dependency when converting to latex or reStructuredText.

The output file created by nbconvert will have the same base name asthe notebook and will be placed in the current working directory. Anysupporting files (graphics, etc) will be placed in a new directory with thesame base name as the notebook, suffixed with _files:

For simple single-file output, such as html, markdown, etc.,the output may be sent to standard output with:

Multiple notebooks can be specified from the command line:

Markdown To Ipynb

or via a list in a configuration file, say mycfg.py, containing the text:

and using the command:

Ipython Notebook Markdown New Line

LaTeX citations¶

Ipython Notebook Markdown

nbconvert now has support for LaTeX citations. With this capability youcan:

• Manage citations using BibTeX.
• Cite those citations in Markdown cells using HTML data attributes.
• Have nbconvert generate proper LaTeX citations and run BibTeX.

For an example of how this works, please see the citations example inthe nbconvert-examples repository.