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](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html).

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 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. When you are ready, commit your changes to the repository by clicking on the green Commit changes button.

10. Add a commit message.

11. 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).

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