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:
Figures and Images that have customisable options through directive metadata
Math that can be referenced via labels
References and Cross References that are more advanced than basic markdown
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#
You can use markdown
to include figures and images but it has limited scope to customise the size and placement.
This introduces figure
admonitions
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:
subject to
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:
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
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:
migrated back to
ipynb
usingjupytext
, oris 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