template/book/syntax_exercises/012.md

Exercise 12: Use admonitions

In this exercise, you will learn how to use admonitions to enhance the readability and structure of your TeachBook content. Admonitions are special highlighted blocks that are useful for tips, warnings, notes, and more.

::::::{topic} Exercise objective
Can you structure your content with different types of admonitions and understand which can be customised?
::::::

Admonitions help to guide readers' attention and make your book more accessible. Full documentation is available [here for the default MyST syntax in your book](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html) and [here for the TeachBooks' extension which allows custom colours](https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html#admonitions).

Using standard admonitions

1. Open a new or existing Markdown file.

2. Start by adding a simple note admonition. This type uses a fixed title ("Note"):

```{note}
This is a note. It always has the title "Note".
```

3. Try adding the following fixed-title admonitions. These cannot have custom titles:

```{tip}
This is a helpful tip!
```

```{warning}
Be careful when editing this file.
```

```{attention}
Important: Save your work frequently.
```

4. Other fixed-title admonitions are listed below. Try use these in your code using the same format used above.

• caution
• important
• seealso
• error
• hint
• danger

Custom titles & styles for admonitions

5. Some admonitions allow you to specify your own title. Try the admonition directive:

```{admonition} Did you know?
You can customise the title of this block using the `admonition` directive.
```

6. Similarly, you can customise titles for dropdown admonitions:

```{dropdown} Click to reveal more info
This content is hidden until the user clicks the title.
```

7. Dropdowns are great for optional or expandable content. Try nesting content inside a dropdown block::

```{dropdown} See the steps
1. Open your file.
2. Write some content.
3. Preview the changes.
```

8. Check your understanding with the summary table below.

Here’s a quick overview:

| Fixed Title Admonitions                                         | Custom Title Admonitions     |
|------------------------------------------------------------------|-------------------------------|
| `note`, `tip`, `warning`, `attention`, `caution`, `important`, `seealso`, `hint`, `danger`, `error` | `admonition`, `dropdown`      |

9. For these admonitions that allow custom titles (admonition, dropdown), you can also apply a custom style using the :class: option. This can be used to change the appearance (e.g. colour or layout) of the block. Try the following examples:

```{admonition} Pro tip!
:class: tip

You can apply styles using the `:class:` option.
```

```{dropdown} Save your work
:class: warning

Don't forget to save your changes regularly to avoid data loss!
```

10. You can apply the :class: dropdown to any admonition, even if it is not originally a dropdown block. This will allow the admonition to be collapsible, making it useful for sections where you'd like to hide additional content until the reader clicks to expand it. Test this out:

```{admonition} Extra Info
:class: dropdown

This content will be hidden until the reader clicks to reveal it. 
```

11. The table below summarizes the classes that can be used together with the admonition and dropdown blocks. Try customize admonitions yourself, using different classes from the table.

Class name	Effect
tip	Gives the block a green background (styled like a helpful tip)
warning	Orange background with a warning-style border
caution	Yellow caution-style background
error / danger	Red background indicating errors or important warnings
dropdown	Makes the block collapsible (content is hidden until clicked)
seealso	Blue background, often used for related info or references
important	Dark blue or purple background for emphasis
note	Subtle grey note block

12. You can also use multiple classes at once by separating them with spaces. For example, :class: important dropdown will give you a collapsible, important-looking block. Try mixing and matching these, using the example below as a base:

```{admonition} Important: Check this out!
:class: important dropdown

This content is both highlighted as important and collapsible.
```

Custom colours for admonitions

13. It is also possible to use specific colours to customize your admonitions, using our extension 'Sphinx-Named-Colours'. This allow you to use default 'CSS' colours or your own custom colours. To do so, it is necessary to add the extension as shown below:

Step A: Add to requirements.txt

Ensure that the package is included in your project's requirements.txt to track the dependency:

sphinx-named-colors

Step B: Enable in _config.yml

In your _config.yml file, add the extension to the list of Sphinx extra extensions:

sphinx:
    extra_extensions:
        .
        .
        .
        - sphinx_named_colors
        .
        .
        .

14. Now we can experiment with custom-coloured admonitions! Go ahead and look at the available CSS Named Colours, and pick a desired colour.

15. Once you have chosen a colour, coloured admonitions can be generated in two ways, depending on how you'd like to structure your content. The first method is by adding the name-colour via :class: to an existing admonition or dropdown type block, similar to what was done above. This can be done as follows:

```{admonition} Custom Colour Example
:class: darkred

This is a custom coloured admonition using `:class: darkred`.
```

16. When using the above method, a new class is introduced: no-title. This suppresses printing of the title bar, even if the title is given. Try this out by adding this class to the above code.

17. The second method of adding coloured admonitions is by directly creating an admonition based on a colour. This method can be used if you'd rather not use the generic type and want a minimal syntax. In this case, the title is optional, and if omitted, the title bar will not appear. Try this out with the code below:

```{darkgreen} Optional Title

This is a green-styled custom admonition.
```

18. For more details, see the documentation of this extension in our manual. This also describes how to add your own custom colours!

19. When you are ready, commit your changes to the repository by clicking on the green Commit changes button.

20. Add a commit message.

21. To see your changes, go to {octicon}play Actions - The most recent workflow run overview.md / the commit message of the commit you just made - Wait for it to finish - In the summary, click on the link of your book shown in the table Branches deployed and under Primary book at root (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).

22. Do you see your change? If you don't see it click CTRL+F5/Control+F5to refresh the page.

:class: note

Before moving on, make sure you understand:
- Which admonitions allow custom titles, and which don’t?
- What is the purpose of a dropdown admonition?
- When might you use a `note` vs. an `admonition`?
- In which ways can you further customize `admonition` blocks?