diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index c363da7..7cbd25a 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -1,15 +1,18 @@ # 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). +To help you illustrate your content, it can be useful to add some type of visual media such as figures, gifs or videos. If you want to add a figure/gif to your 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? +Can you add figures and videos to your page? :::::: ```{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!). ``` +## Adding figures + 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). @@ -51,13 +54,69 @@ align: center ``` ```` -6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -7. Add a commit message. +## Adding videos -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). +7. You can also embed videos (e.g., from YouTube) into your book using the [`sphinx-iframes`](https://github.com/TeachBooks/sphinx-iframes) extension. Firstly the extension needs to be installed. If you're working locally, install the module using pip: + +```bash +pip install sphinx-iframes +``` + +8. After installation, add the package in your `requirements.txt` to track the dependency: + +``` +sphinx-iframes +``` + +9. Now the extension needs to be enabled. Do this by adding the extension to the list of Sphinx extra extensions in your `_config.yml` file (**important**: underscore, not dash): + +```yaml +sphinx: + extra_extensions: + . + . + . + - sphinx_iframes + . + . + . +``` + +10. You can also configure several values which can be added to `_config.yml`, such as default video sizes. Add the following: + +```yaml +sphinx: + config: + iframe_blend: true + iframe_width: calc(100% - 2.8rem) + iframe_aspectratio: auto 2 / 1 +``` + +11. Let's test out this extension! Use the `{video}` directive to embed a video. Here’s an example you can try using a public YouTube video: + +````md +```{video} https://www.youtube.com/watch?v=x2eonqw5M6o +:width: 80% +:height: 400px +:class: blend +``` +```` + +```{tip} +The blend class helps the video look good in dark mode! +``` + +12. Try to change the `width`and `height` of the video in the previous example to customise the display. + +13. When you're ready, commit your changes to the repository by clicking the green `Commit changes` button. + +14. Add a commit message. + +15. To see your changes, go to {octicon}`play;1em` `Actions` – The most recent workflow run (`overview.md` / your commit message) – Wait for it to finish – In the summary, click on the link under `Branches deployed` and under `Primary book at root`. + +16. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. -9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding :class: note @@ -67,5 +126,6 @@ Before moving on to the next exercise, make sure you understand the following: - 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? - +- What extension must be added to embed videos in the book? +``` ``` \ No newline at end of file