mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-13 06:35:52 +00:00
64 lines
3 KiB
Markdown
64 lines
3 KiB
Markdown
# 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?
|
||
```
|