manual_teachbooks/book/basic-features/badges.md

# Badges, Buttons & Icons

<a href="https://jupyterbook.org/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> provides a range of features which are visually appealing and functional. These elements can enhance the interactivity and visual design of your book, offering additional information or links in a compact and visually engaging way. The badges, buttons and icons are made available through Sphinx and they themselves wrote a [documentation](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html) about it.

## Badges

Badges are small visual indicators often used to convey concise or important information. They can be very useful for categorising or tagging content for the reader like has been done for the subchapters under the [features](../features/overview.md) chapter of this manual. There are three types of badges: plain, link and reference. They are fully customizable and can simply be added with Markdown syntax:

| Type   | Badge                                                    | Code Syntax                                                            |
|--------|----------------------------------------------------------|------------------------------------------------------------------------|
| Plain  | {bdg-primary}`plain_text`                                | ``` {bdg-primary}`plain_text` ``` 
| Link   | {bdg-link-primary}`https://teachbooks.io/`               | ``` {bdg-link-primary}`https://teachbooks.io/` ``` |
| Hidden Link | {bdg-link-primary}`TeachBooks <https://https://teachbooks.io/>` | ``` {bdg-link-primary}`TeachBooks <https://https://teachbooks.io/> ` ``` |
| Reference | {bdg-ref-primary}`my_ref`                             | ``` {bdg-ref-primary}`my_ref` ```                                           |

Here's an overview of all the available colours:

| Full Colour                   | Code Syntax                      | Colour Outline                | Code Syntax                           |
|-------------------------------|----------------------------------|-------------------------------|---------------------------------------|
| {bdg}`my_text`                | ``` {bdg}`my_text` ```           |                               |                                       |
| {bdg-primary}`my_text`        | ``` {bdg-primary}`my_text` ```   | {bdg-primary-line}`my_text`   | ``` {bdg-primary-line}`my_text` ```   |
| {bdg-secondary}`my_text`      | ``` {bdg-secondary}`my_text` ``` | {bdg-secondary-line}`my_text` | ``` {bdg-secondary-line}`my_text` ``` |
| {bdg-success}`my_text`        | ``` {bdg-success}my_text` ```    | {bdg-success-line}`my_text`   | ``` {bdg-success-line}`my_text` ```   |
| {bdg-info}`my_text`           | ``` {bdg-info}my_text` ```       | {bdg-info-line}`my_text`      | ``` {bdg-info-line}`my_text` ```      |
| {bdg-warning}`my_text`        | ``` {bdg-warning}my_text` ```    | {bdg-warning-line}`my_text`   | ``` {bdg-warning-line}`my_text` ```   |
| {bdg-danger}`my_text`         | ``` {bdg-danger}my_text` ```     | {bdg-danger-line}`my_text`    | ``` {bdg-danger-line}`my_text` ```    |
| {bdg-light}`my_text`          | ``` {bdg-light}my_text` ```      | {bdg-light-line}`my_text`     | ``` {bdg-light-line}`my_text` ```     |
| {bdg-muted}`my_text`          | ``` {bdg-muted}my_text` ```      | {bdg-muted-line}`my_text`     | ``` {bdg-muted-line}`my_text` ```     |
| {bdg-dark}`my_text`           | ``` {bdg-dark}my_text` ```       | {bdg-dark-line}`my_text`      | ``` {bdg-dark-line}`my_text` ```      |
| {bdg-white}`my_text`          | ``` {bdg-white}my_text` ```      | {bdg-white-line}`my_text`     | ``` {bdg-white-line}`my_text` ```     |
| {bdg-black}`my_text`          | ``` {bdg-black}my_text` ```      | {bdg-black-line}`my_text`     | ``` {bdg-black-line}`my_text` ```     |


## Buttons

Buttons provide a way to create clickable elements that are more attractive than links. Jupyter-Book supports buttons using Markdown making them highly customizable. It is possible to link to external websites as well as chapters within your book. To link to an external page, `{button-link}` and `{button-ref}` must be used when linking to a different part of your book.

The basic code syntax for creating a button is as follows:

```{button-link} https://teachbooks.io
``` 


```{button-red} book\intro.md
``` 

Buttons can be customized in markdown in a similar way as figures. You can experiment with these styles to create buttons that align with your book's theme. Here are the set of parameters which can be customized:


| Parameter                     | Options                          | Functionality                 |
|-------------------------------|----------------------------------|-------------------------------|
| colour | primary, secondary, success, danger, warning, info, light, dark, muted | Set the color of the button (background and font)|
| outline                       | /                                 | white button, coloured outline|
| align                         | left, right, center              | Align the button on the page  |
| expand                        | /                                | Expand to fit parent width    |
| click-parent                  | /                                | Make parent container also clickable |
| tooltip                       | /                                | Add tooltip on hover          |
| shadow                        | /                                | Add shadow CSS          |
| class                         | /                                | Additional CSS classes         |

Finally here are some examples:


## Icons

Icons can be included to visually represent actions or categories. Jupyter-Book supports FontAwesome icons, which can be integrated using HTML syntax.

Adding Icons
To add an icon, use the following syntax:

markdown
Code kopiëren
<i class="fas fa-book"></i> Jupyter-Book
This example adds a "book" icon before the text "Jupyter-Book."

Combining Buttons and Icons
Icons can also be included within buttons for a modern, professional look:

markdown
Code kopiëren
<a href="https://jupyterbook.org" class="btn btn-primary">
    <i class="fas fa-download"></i> Download Book
</a>
This button includes a "download" icon alongside text.

4. Use Cases
Here are some practical use cases for badges, buttons, and icons in a Jupyter-Book:

Badges: Highlight software version, repository status, or contributors.
Buttons: Link to key sections of your book, such as downloads or external resources.
Icons: Add visual appeal or clarity to navigation links or labels.
Incorporating these elements into your Jupyter-Book improves both the aesthetic and functionality of your book, creating a more engaging experience for readers.