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

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.

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:

   sphinx:
     extra_extensions:
       - teachbooks_favourites
   

4. Commit and rebuild your book — all favourite extensions will now load automatically with their default settings.

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:

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.

Contribute your favourite

6. Think an extension deserves a place among the favourites? You can contribute by opening an issue on GitHub, or 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.

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.

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