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