template/book/extension_exercises/017.md

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 many extensions. For more information on each extension and how to use it, see the TeachBooks manual

If you cloned your book from the TeachBooks Template, the TeachBooks-Favourites extension is **already included and activated**.

Customising your favourites

1. The TeachBooks template contains all the configuration options for all of the extensions included in TeachBooks-Favourites. Open _config.yml and scroll to the sphinx section to see the options.

2. 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:

   sphinx:
     extra_extensions:
       - sphinx_image_inverter
       - sphinx_iframes
       - teachbooks_sphinx_tippy
   

   Start with `teachbooks_favourites` enabled — it’s a great default for beginners. As your project grows, you can refine which extensions stay active.
   

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

4. Add a commit message.

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

6. You should see that the accessibility button (from sphinx_accessibility) is now gone.

Contribute your favourite

7. Think an extension deserves a place among the favourites? You can contribute by opening an issue on GitHub, or add it yourself by submitting a pull request that adds it to:

   • README.md
   • pyproject.toml
   • src/teachbooks_favourites/__init__.py

   Extensions must be stable, open-source, and enhance the TeachBooks authoring or learning experience.
   

: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?