Best practices for including local image in notebook

[cranmer]

I often have notebooks that want to include an image and not rely on a remote URL.
What is the best practice for this? Currently, I am putting images in a directory like assets or images, but they don't seem to be copied over when building the site and the path is going to change. I know what to do for images in .md files, but not for notebooks. Thanks!

[chrisjsewell]

Hey @cranmer images should work exactly the same when using .md and .ipynb since they both use the myst-parser.
There is also now the option to use HTML image syntax (although this version of myst-parser is not used by jupyter-book just yet, but hopefully by this week!): https://myst-parser.readthedocs.io/en/latest/using/syntax.html#images

[chrisjsewell]

If there is any issue, if you could provide an example notebook where this is not working

[cranmer]

Here is an example:
https://cranmer.github.io/stats-ds-book/autodiff-tutorial.html
https://github.com/cranmer/stats-ds-book/blob/master/book/autodiff-tutorial.ipynb

The notebook was made without the book in mind. The content of the last markdown cell is:
<img src="./assets/schmidhuber.png" alt="A Matrix Vector Product" width="700"/>
which is why it is broken. But I'm not sure what ways of including the image are recommended inside the notebook. I'm still not quite sure which parts of the myst markdown will work inside the notebooks... eg. are roles supported? And will they work in the book and when running the notebook (eg. with lauch binder)?

[chrisjsewell]

All MyST Markdown works in the notebooks 😄 BUT jupyter-book is currently pinned to an older version of myst-parser, as I'm just going through and propagating the changes up to it (hopefully within the next few days)

I'm not quite sure what you mean by roles working in Binder though?

[cranmer]

Sorry I wasn't clear.

If I have this code in a markdown cell in the notebook:

## Test Myst markdown:

figure role:

```{figure} ./assets/schmidhuber.png
---
height: 150px
name: my-figure
---
Here is my figure caption!
```

image role:

```{image} ./assets/schmidhuber.png
:name: label
```

vanilla markdown
![](./assets/schmidhuber.png)

Then all three display in the Jupyter book, but the first two do not display images when I'm actually running the notebook (either locally or on Binder) because (I presume) the Jupyter notebook doesn't know anything about the {image} and {figure} roles that are defined by sphinx and myst. The problem with the vain all markdown is the image is huge and I'd like to set the height or width (which is why originally it was done with raw HTML <img> tag, but that breaks when building the book because the location of the image changes).

Alternatively, I can display the image with

import IPython
IPython.display.Image('./assets/schmidhuber.png')

and that displays in both when executing the notebook or when building and viewing the book, but it has extra code cells that I'd rather avoid.

Does that make more sense?

What would be nice is a recommendation for how to display a local image in the notebook with custom height/width that will display both when the notebook is being run locally or on binder and display in the book after it is built.

[cranmer]

This is an image of the notebook when running locally:

[chrisjsewell]

New in v0.8.0 see https://jupyterbook.org/content/figures.htm 😄

[cranmer]

Fantastic! That fixed a bunch of broken images in my book!