template/book/syntax_exercises/008.md

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).

::::::{topic} Exercise objective Can you add figures to your page? ::::::

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 - {octicon}upload;1em 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 MyST documentation):

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

<caption text>
```

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

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. `figures/<figure in figures-subdirectory>.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../figure/<figure in figures-subdirectory which is located two folder above the current page>` )

6. 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>
```

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

7. Add a commit message.

8. To see you changes, go to {octicon}play;1em 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).

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