Exercise 8: Add visual media

Exercise 8: Add visual media#

To help you illustrate your content, it can be useful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale).

Note

Unless you are using a file format like *.svg, the raw contents of a visual media file typically are not human-readable or have a binary file format. This is not an ideal file type to use with Git. When just beginning to learn about all the tools associated with a TeachBook, we recommend you keep things simple and do whatever is easiest for you. Note, however, that as your book grows, especially if you use a lot of non-svg images, you may want to find a different way to store them (guidance will be provided on this soon in the TeachBooks Manual—stay tuned!).

  1. You will first need to upload your media to the repository. Navigate to the folder called figures (book/figures) and make sure you are in the right branch. On the right top, click on Add file - Upload new file. Note that you can store your files in another folder within the book directory too. However it’s good practice to store figures in a separate folder (eventually per chapter).

  2. Choose the visual media you want to upload. Remember its file name, including its file extension as you will need it later.

  3. Commit your changes.

  4. Now let’s add the figure to a chapter. Navigate to the file you want to work in (for example book/some_content/overview.md) and make sure you’re in the same branch as where you’ve added your figure.

  5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the JupyterBook documentation):

```{figure} figures/<new_figure>.png
---
width: 80%
align: center
---
<caption text>
```

Warning

Make sure the file extension of your figure is correct because markdown differentiates capital letters!

Tip

If your figure is in a different directory than your chapter, you’ll need to refer it using relative parts. If your figure is in a subdirectory of the directory of the chapter, go deeper with subdirectory/ (e.g. <subdirectory>/<figure in subdirectory>.png). If your figure is in another directory, move upwards with ../ (e.g. ../../<subdirectory>/<figure which is located in a subdirectory two folders above the current page.png> )

  1. To link and display an online figure, you can use the same {figure} directive. Just past in the :

```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg
---
width: 80%
align: center
---
<caption>
```

  1. When you are ready, commit your changes to the repository by clicking on the green Commit changes button.

  2. Add a commit message.

  3. To see you changes, go to Actions - The most recent workflow run overview.md / the commit message of the commit you just made - Wait for it to finish - In the summary, click on the link of your book shown in the table Branches deployed and under Primary book at root (getting bored of waiting? There’ll be exercising on doing this locally which prevents you from waiting).

  4. Do you see your change? If you don’t see it click CTRL+F5/Control+F5to refresh the page.

Check your understanding

Before moving on to the next exercise, make sure you understand the following:

  • Where should you upload your visual media files in the repository?

  • What is the recommended practice for storing figures in the book directory?

  • What should you be cautious about when specifying the file extension of your figure?

  • How do you refer to a figure located in a different directory than your chapter?