chapter 12

book/_toc.yml

@@ -23,6 +23,7 @@ parts:
       - file: syntax_exercises/009.md
       - file: syntax_exercises/010.md
       - file: syntax_exercises/011.md
+      - file: syntax_exercises/012.md
     - file: references.md
     - file: changelog.md
     - file: credits.md

book/syntax_exercises/010.md

@@ -67,11 +67,11 @@ The syntax to type a table is a bit cumbersome. You could make use of online too
 
 8. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
 
-8. Add a commit message.
+9. Add a commit message.
 
-9. 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).
+10. 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).
 
-10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
+11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
 
 
 

book/syntax_exercises/012.md

@@ -0,0 +1,118 @@
+# 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?  
+::::::
+
+```{tip}
+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"):
+
+````md
+```{note}
+This is a note. It always has the title "Note".
+```
+````
+
+3. Try adding the following fixed-title admonitions. These cannot have custom titles:
+
+````md
+```{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:
+
+````md
+```{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:
+
+````md
+```{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::
+
+````md
+```{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.
+
+```{admonition} Summary: Custom vs. Fixed titles
+Here’s a quick overview:
+
+| Fixed Title          | Custom Title Allowed |
+|----------------------|----------------------|
+| `note`               | `admonition`         |
+| `tip`                | `dropdown`           |
+| `warning`            |                      |
+| `attention`          |                      |
+| `caution`            |                      |
+| `important`          |                      |
+| `seealso`            |                      |
+| `hint`               |                      |
+| `danger`             |                      |
+| `error`              |                      |
+```
+
+
+
+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`+`F5`to refresh the page.
+
+```{admonition} Check your understanding
+: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`?
+```
+
+