Migrate to "callouts" extension in docs

Author: oprypin

docs/extras.md

@@ -41,23 +41,17 @@ In addition to the [usual admonition styles](https://squidfunk.github.io/mkdocs-
 }
 </style>
 
-!!! todo
-    `TODO: ` `!!! todo`
+TODO: `TODO: ` `!!! todo`
 
-!!! note
-    `NOTE: ` `!!! note`
+NOTE: `NOTE: ` `!!! note`
 
-!!! bug
-    `BUG: ` `!!! bug`
+BUG: `BUG: ` `!!! bug`
 
-!!! fixme
-    `FIXME: ` `!!! fixme`
+FIXME: `FIXME: ` `!!! fixme`
 
-!!! deprecated
-    `DEPRECATED: ` `!!! deprecated`
+DEPRECATED: `DEPRECATED: ` `!!! deprecated`
 
-!!! optimize
-    `OPTIMIZE: ` `!!! optimize`
+OPTIMIZE: `OPTIMIZE: ` `!!! optimize`
 
 Both the default styles and the extra styles work with both the ["callouts" extension][] (write them in all-uppercase) and the ["admonition" extension][] (write them in all-lowercase).
 

docs/quickstart/ci.md

@@ -11,8 +11,6 @@ You can build and publish the website automatically on push using GitHub Pages a
     * Do *not* disable the workflow for non-*master* branches or pull requests. It is nice to ensure that the site builds (there can be errors!), instead at the bottom we prevent only the actual *deploy* action from being executed on non-*master*/non-*pushes*.
     * Dependencies are installed from `requirements.txt`. Make sure you've [populated it](python-dependencies.md).
 
-!!! tip
-    You can freely have a "dev" branch for working on docs that aren't ready for release yet. Then just merge it into the main one when ready.
+TIP: You can freely have a "dev" branch for working on docs that aren't ready for release yet. Then just merge it into the main one when ready.
 
-!!! tip
-    Your docs don't have to be in the same repository as the main code. In fact, the doc site can span several projects! See "Multi-repo setup" [in Showcase](../showcase.md#athena-framework).
+TIP: Your docs don't have to be in the same repository as the main code. In fact, the doc site can span several projects! See "Multi-repo setup" [in Showcase](../showcase.md#athena-framework).

docs/quickstart/index.md

@@ -23,10 +23,9 @@ $ pip install mkdocs-material mkdocstrings-crystal
 
 This assumes you have [Python][] installed, with `pip` available.
 
-!!! tip
-    You might want to install these in a [virtualenv][] (i.e. localized just to this project).
-
-    And check out how to **[manage Python dependencies](python-dependencies.md)** long-term.
+> TIP: You might want to install these in a [virtualenv][] (i.e. localized just to this project).
+>
+> And check out how to **[manage Python dependencies](python-dependencies.md)** long-term.
 
 ## Base config
 

docs/quickstart/migrate.md

@@ -23,10 +23,9 @@ $ pip install mkdocs-material mkdocstrings-crystal mkdocs-gen-files mkdocs-liter
 
 This assumes you have [Python][] installed, with `pip` available.
 
-!!! tip
-    You might want to install these in a [virtualenv][] (i.e. localized just to this project). Otherwise, they go to `~/.local/lib/python*`.
-
-    And check out how to **[manage Python dependencies](python-dependencies.md)** long-term.
+> TIP: You might want to install these in a [virtualenv][] (i.e. localized just to this project). Otherwise, they go to `~/.local/lib/python*`.
+>
+> And check out how to **[manage Python dependencies](python-dependencies.md)** long-term.
 
 ## Base config
 
@@ -56,8 +55,7 @@ Let's configure [MkDocs][] with *mkdocstrings-crystal*. Add/merge this config as
     `extra_css`
     :   Don't forget to copy and include the [recommended styles](../styling.md#recommended-styles).
 
-!!! important
-    The "literate-nav" plugin must appear *before* "section-index" in the list, because it overwrites the nav.
+IMPORTANT: The "literate-nav" plugin must appear *before* "section-index" in the list, because it overwrites the nav.
 
 ## Generate doc stub pages
 

docs/quickstart/python-dependencies.md

@@ -4,8 +4,7 @@ There are countless ways to do it, but this document is nice for people not fami
 
 This assumes you have [Python][] installed, with `pip` available.
 
-!!! note
-    Of course, you can just always run a bare `pip install` (without versions), but dependencies can break from under you with upgrades.
+NOTE: Of course, you can just always run a bare `pip install` (without versions), but dependencies can break from under you with upgrades.
 
 We suggest to *lock* all dependencies' versions (recursively), so the same ones are always used.
 
@@ -22,8 +21,7 @@ Install the [pip-compile][] tool:
 $ pip install pip-tools
 ```
 
-!!! note
-    This is needed only to manage the lock files; it won't be a permanent dependency.
+NOTE: This is needed only to manage the lock files; it won't be a permanent dependency.
 
 And run it:
 
@@ -46,11 +44,9 @@ Now anyone ([including automation](ci.md)) can install the exact same dependenci
 $ pip install -r requirements.txt
 ```
 
-!!! tip
-    If you'll be maintaining several projects with different dependencies, you might want to install packages in a [virtualenv][] (effectively localized just to this project's folder).
+TIP: If you'll be maintaining several projects with different dependencies, you might want to install packages in a [virtualenv][] (effectively localized just to this project's folder).
 
-!!! important
-    Both `requirements.in` and `requirements.txt` should be checked into source control.
+IMPORTANT: Both `requirements.in` and `requirements.txt` should be checked into source control.
 
 Depending on the layout of project, you have many options where to store those files:
 

docs/requirements.txt

@@ -3,3 +3,4 @@ mkdocs-material>=7.1.4
 mkdocs-section-index>=0.3.0
 mkdocstrings>=0.15.0
 pymdown-extensions>=8.2
+markdown-callouts>=0.2

mkdocs.yml

@@ -41,6 +41,7 @@ markdown_extensions:
   - pymdownx.details
   - pymdownx.snippets:
       check_paths: true
+  - callouts
   - admonition
   - def_list
   - toc: