# 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](https://teachbooks.io/manual/features/favourites.html#)

```{note}
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:

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

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](https://github.com/TeachBooks/TeachBooks-Favourites), or add it yourself by 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.
    ```

```{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?  
```