MyST Demo in JupyterLab

MyST Demo in JupyterLab#

Conversion using jupytext

This is the same as MyST demo notebook that has been converted to myst markdown using jupytext and rendered using Jupyter Book.

Note

This is a demo document for testing elements of the MyST syntax in jupyterlab-mystjs

This plugin for jupyterlab enables the jupyter rendering system to render additional syntax elements that are introduced by MyST markdown.

These elements include:

  1. Admonitions

  2. Figures and Images that have customisable options through directive metadata

  3. Math that can be referenced via labels

  4. References and Cross References that are more advanced than basic markdown

  5. Footnotes

in addition to full support of CommonMark markdown

Standard Markdown#

All the standard markup features also supported with things like bold and italic and tables:

name

description

@mmcky

quantecon nerd

and section breaks

Admonitions#

You can use note, and generic admonition objects:

```{note}
This is a `note` with no title support
```

which renders as

Note

This is a note with no title support

or you can use admonition such as:

```{admonition} This has a Title
And this is using the `admonition` directive
```

which renders as

This has a Title

And this is using the admonition directive

It also includes support for warnings or tip admonitions

```{tip}
This is a tip
```

which renders as

Tip

This is a tip

and this is a warning

```{warning}
Watch out!
```

which renders as

Warning

Watch out!

!ls 

_static  myst-demo-jupytext.md	myst-demo.ipynb

Figures and Images#

Warning

This is currently not working using this extension

executablebooks/jupyterlab-mystjs#8

You can use markdown to include figures and images but it has limited scope to customise the size and placement.

This introduces figure admonitions

../_images/graph4.png

Math#

You can use both markdown based math syntax such as

$$
\max \mathbb E \sum_{t=0}^{\infty} \beta^t u(c_t)
$$

subject to

$$
a_{t+1} + c_t \leq w z_t + (1 + r) a_t
\quad
c_t \geq 0,
\quad \text{and} \quad
a_t \geq -B
$$(constraint)

which renders:

\[ \max \mathbb E \sum_{t=0}^{\infty} \beta^t u(c_t) \]

subject to

(1)#\[ a_{t+1} + c_t \leq w z_t + (1 + r) a_t \quad c_t \geq 0, \quad \text{and} \quad a_t \geq -B \]

and the labeled constraint can be referenced using

{eq}`constraint`

and this renderes a hover view such as (1)

You can also use the directive syntax such as

```{math}
:label: matrix
Ax = b
```

which renders as:

(2)#\[Ax = b\]

and the label acts in the same way as the short hand syntax displayed above

You can generate links using inline role

{eq}`matrix`

that can be linked to (2)

References and Cross References#

You can use numref role to generate numbered references such as to a table

see {numref}`my-table`

where the table is referenced by name

```{list-table}  Caption text
:name: my-table

*   - Head 1
*   - Row 1
```

which renders as

see Table 1

where the table is referenced by name

Table 1 Caption text#

Head 1

Row 1

Linking to other parts of a document#

You can also create links to titles using the shorthand label

An interesting section#

to another location An interesting section and this ref will include the section title as the text

Using footnote directives#

Example:

Here is an example footnote[1]

with the following reference syntax

[^1]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

This won’t render the actual footnote at the bottom of the notebook but will convert it to a hover footnote instead.

Note

@mmcky to check this transfers the footnote using jupytext

Things that don’t work as expected or exactly the same as Jupyter Book#

Using code-cell in a markdown cell#

The code-cell directive from jupyter-book will be rendered as an executable component in JupyterBook when using myst:markdown files.

However in the jupyterlab context these blocks initially render as syntax highlighted code blocks within the markdown cells.

Note

@mmcky to add issue for mystjs to convert to excecutable blocks executablebooks/jupyterlab-mystjs#9

Tip

If you use jupytext to convert the ipynb file to md file these {code-cell} directives will be passed through to the md file.

This means that if that md file is then either:

  1. migrated back to ipynb using jupytext, or

  2. is compiled with jupyterbook

then that code will get executed.

Therefore this is only an issue if copy/paste existing myst markup into a notebook and are expected those blocks to convert to executable code cells.

Example:

This code-cell

```{code-cell} python3
import pandas as pd
```

should be executable

import pandas as pd

but is shown as a syntax highlighted cell