Create 007.md

book/exercises/007.md

@@ -0,0 +1,67 @@
+# Exercise 8: Add extensions to your book
+
+TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels.
+
+\::::::{topic} Exercise objective
+Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` in your TeachBooks book?
+\::::::
+
+1. In your book repository, open the `requirements.txt` file. This file lists the Python packages that will be installed to build your book.
+
+2. Add the following line to the bottom of the `requirements.txt` file:
+
+   ```
+   git+https://github.com/TeachBooks/Sphinx-Indexed-Definitions.git
+   ```
+
+   This tells the build system to install the extension directly from GitHub.
+
+3. Next, open `_config.yml` and add the extension to your `sphinx` configuration block:
+
+   ```yaml
+   sphinx:
+     extra_extensions:
+       - indexed_definitions
+   ```
+
+   This ensures Sphinx loads the extension when building your book.
+
+4. Now you can use the new directive provided by the extension. Try adding the following to one of your Markdown files in the `book/` directory:
+
+   `````md
+   ````{definition} Term
+   :label: term-definition
+   A word or phrase used to describe a concept or object.
+   `````
+
+   This will render a labelled, indexed definition that you can refer to from other parts of your book.
+
+5. Try to reference the definition in another file using `{ref}` followed by the given label, as shown below:
+ 
+
+   ```md
+   For more details, see the definition of {ref}`term-definition`.
+   ```
+
+   This will appear as a hyperlink that takes the reader directly to the definition. 
+
+6. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation.
+
+
+7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
+
+8. Add a commit message.
+
+9. To see your 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).
+10. 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
+
+Before moving on, make sure you understand:
+
+* How do you add a new extension to a TeachBooks book?
+* What is the purpose of the `requirements.txt` and `_config.yml` files?
+* How can you confirm that your extension is working correctly?
+```