teachbook favourites

book/_toc.yml

@@ -34,6 +34,7 @@ parts:
       - file: extension_exercises/014.md
       - file: extension_exercises/015.md
       - file: extension_exercises/016.md
+      - file: extension_exercises/017.md
   - caption: Miscellaneous
     chapters:
     - file: references.md

book/extension_exercises/017.md

@@ -0,0 +1,112 @@
+# TeachBooks Favourites
+
+The **TeachBooks-Favourites** extension brings together TeachBooks’ most-used and most-loved features in one convenient package. It bundles several Sphinx extensions—developed both by TeachBooks and others—into a single install, making it easier to start a new TeachBook with all recommended functionality already enabled.
+
+This exercise will guide you through installing the **TeachBooks-Favourites** extension, enabling it in your configuration, and exploring what it includes.
+
+::::::{topic} Exercise objective
+Can you install and activate the TeachBooks-Favourites extension, and identify which tools it automatically enables?
+::::::
+
+## Explore what’s included
+
+The TeachBooks-Favourites bundle includes the following extensions. For more information on each extension and how to use it, see the [TeachBooks manual](https://teachbooks.io/manual/features/favourites.html#)
+
+| Extension                   | Description                                                    |
+| --------------------------- | -------------------------------------------------------------- |
+| Sphinx-Thebe                | Enables live executable code cells.                            |
+| JupyterBook Patches         | Improves compatibility and fixes common issues in JupyterBook. |
+| Download Link Replacer      | Ensures consistent download button behavior.                   |
+| Sphinx Image Inverter       | Adapts images and figures for dark mode.                       |
+| Sphinx Iframes              | Embeds external content like dashboards and videos.            |
+| Sphinx Exercise             | Supports self-assessment exercises.                            |
+| TeachBooks Sphinx Tippy     | Adds helpful tooltips to content.                              |
+| Sphinx Named Colors         | Provides colour names compatible with LaTeX and HTML.          |
+| Sphinx Dropdown Toggle      | Creates collapsible sections and hints.                        |
+| Sphinx Proof                | Supports theorem- and proof-like blocks.                       |
+| Sphinx Code Examples        | Displays and organizes code examples clearly.                  |
+| Sphinx Accessibility        | Improves accessibility compliance for readers.                 |
+| Sphinx Toggle Button        | Toggles visibility of content blocks.                          |
+| Notebook Execution Patterns | Defines consistent notebook execution behavior.                |
+| Sphinx Launch Buttons       | Adds “Launch in Binder/Colab” buttons for notebooks.           |
+| Sphinx New Tab Link         | Opens external links in a new browser tab.                     |
+
+```{note}
+If you cloned your book from the TeachBooks Template, the TeachBooks-Favourites extension is **already included and activated**.
+```
+
+## Install the extension
+
+If you’re working in a custom or manually configured repository, follow these steps to install it.
+
+1. Install the package using `pip`:
+
+   ```
+   pip install git+https://github.com/TeachBooks/TeachBooks-Favourites
+   ```
+
+2. Add it to your `requirements.txt`:
+
+   ```
+   git+https://github.com/TeachBooks/TeachBooks-Favourites
+   ```
+
+3. Enable it in `_config.yml`:
+
+   ```yaml
+   sphinx:
+     extra_extensions:
+       - teachbooks_favourites
+   ```
+
+4. Commit and rebuild your book — all favourite extensions will now load automatically with their default settings.
+
+```{tip}
+If you’re using GitHub online only (without local installation), simply edit your `_config.yml` and `requirements.txt` files directly in the browser, then commit. The next automatic build will include the extension.
+```
+
+## Customising your favourites
+
+5. If you want to use only some of the included extensions, you can remove `teachbooks_favourites` from `_config.yml` and instead add the specific extensions you need. This gives you full control over which features are loaded. Try this out with the example below:
+
+```yaml
+sphinx:
+  extra_extensions:
+    - sphinx_image_inverter
+    - sphinx_iframes
+    - teachbooks_sphinx_tippy
+```
+
+
+```{tip}
+Start with `teachbooks_favourites` enabled — it’s a great default for beginners. As your project grows, you can refine which extensions stay active.
+```
+
+## Contribute your favourite
+
+6. Think an extension deserves a place among the favourites? You can contribute by opening an issue on [GitHub](https://github.com/TeachBooks/TeachBooks-Favourites), or submitting a **pull request** that adds it to:
+
+  * `README.md`
+  * `pyproject.toml`
+  * `src/teachbooks_favourites/__init__.py`
+
+```{note}
+Extensions must be stable, open-source, and enhance the TeachBooks authoring or learning experience.
+```
+
+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` **Actions** → select the most recent workflow run → wait for it to finish → click the link under *Branches deployed* and *Primary book at root*.
+
+10. Don’t see your change? Press `CTRL+F5` / `Control+F5` to refresh the page.
+
+```{admonition} Check your understanding
+:class: note
+
+Before moving on, make sure you can answer:
+- What is the TeachBooks-Favourites extension?  
+- How do you enable it in `_config.yml`?  
+- What should you do if you only want to load a few of the extensions?  
+```