--- jupytext: text_representation: extension: .md format_name: myst format_version: 0.13 jupytext_version: 1.14.2 kernelspec: display_name: Python 3 (ipykernel) language: python name: python3 --- +++ {"tags": []} # MyST Demo in JupyterLab ```{admonition} Conversion using jupytext This is the same as {download}`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](https://myst.tools/docs/spec/admonitions) 2. [Figures and Images](https://myst.tools/docs/spec/figures) that have customisable options through directive metadata 3. [Math](https://myst.tools/docs/spec/math) that can be referenced via labels 4. [References and Cross References](https://myst.tools/docs/spec/references) that are more advanced than basic markdown 5. [Footnotes](https://myst.tools/docs/spec/footnotes) in addition to full support of [CommonMark](https://myst.tools/docs/spec/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 ```{admonition} 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! ``` ```{code-cell} ipython3 !ls ``` ## Figures and Images ```{warning} This is currently **not** working using this extension https://github.com/executablebooks/jupyterlab-mystjs/issues/8 ``` You can use `markdown` to include figures and images but it has limited scope to customise the size and placement. ![](_static/graph4.png "Network Diagram") This introduces `figure` admonitions ```{figure} _static/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 $$ 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) and the labeled `constraint` can be referenced using ``` {eq}`constraint` ``` and this renderes a hover view such as {eq}`constraint` You can also use the directive syntax such as ```` ```{math} :label: matrix Ax = b ``` ```` which renders as: ```{math} :label: matrix 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 {eq}`matrix` +++ ## 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 {numref}`my-table` where the table is referenced by name ```{list-table} Caption text :name: my-table * - Head 1 * - Row 1 ``` --- ### Linking to other parts of a document You can also create links to titles using the shorthand label (interesting-section)= #### An interesting section to another location {ref}`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. [^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. :::{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 https://github.com/executablebooks/jupyterlab-mystjs/issues/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 ```{code-cell} python3 import pandas as pd ``` but is shown as a syntax highlighted cell +++