From af3c927d71b3ad8814d2b8ddd12a383a0d59b782 Mon Sep 17 00:00:00 2001
From: Leonardo Rivera <leodrivera@gmail.com>
Date: Tue, 15 Nov 2022 06:41:31 -0300
Subject: [PATCH] DOCS: Improve custom admonitions documentation (#1777)
* Improve custom admonitions documentation
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Apply suggestions from code review
Co-authored-by: Chris Holdgraf <choldgraf@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Chris Holdgraf <choldgraf@gmail.com>
---
docs/advanced/html.md | 47 +++++++++++++++++++++++++++++++++++--------
1 file changed, 39 insertions(+), 8 deletions(-)
diff --git a/docs/advanced/html.md b/docs/advanced/html.md
index ca91471d..e508839f 100644
--- a/docs/advanced/html.md
+++ b/docs/advanced/html.md
@@ -49,25 +49,31 @@ A more verbose but "stable" approach is to use the `:class:` keyword argument wh
:::
Currently, using the `{admonition}` directive with a title creates a CSS class based on the title of the admonition.
-For example, an admonition title of `Here's my title` will result in a class name of `admonition-heres-my-title`.
+For example, an admonition title of `Here's my title` will result in a class name of `admonition-here-s-my-title`.
-You can leverage this pattern to quickly create custom admonitions.
-For example, create a `myadmonitions.css` under `mybook/_static` with the following CSS:
+On the other hand, by using the `:class:` keyword argument, it will create a class with the keyword previously chosen.
+For example, a custom class defined as `my-custom-class` will result in a class named as `my-custom-class`.
+
+You can leverage either of these patterns to quickly create custom admonitions.
+There is an example of each below.
+In each case, begin by creating a `myadmonitions.css` file under `mybook/_static` and add CSS rules to it.
+
+**Using the `{admonition}` directive with a title**
```css
-.admonition-extra-credit {
+div.admonition-extra-credit {
border-left-color: rgba(0, 246, 16, 1);
}
-.admonition-extra-credit .admonition-title {
+div.admonition-extra-credit .admonition-title {
background-color: rgba(0, 246, 16, .1);
}
-.admonition-extra-credit .admonition-title:before {
+div.admonition-extra-credit .admonition-title:before {
color: rgba(0, 246, 16, 1);
content: '\f19d';
}
```
-then in your book, define an admonition like so:
+Then, in your book, define an admonition like so:
````md
```{admonition} Extra credit
@@ -75,7 +81,32 @@ An "extra credit" exercise is presented here.
```
````
-The admonitions should be styled according to your CSS rules when you build your book.
+**Using the `:class:` keyword argument**
+
+```css
+div.extra-credit {
+ border-left-color: rgba(var(--pst-color-success), 1);
+}
+div.extra-credit .admonition-title {
+ background-color: rgba(var(--pst-color-success), .1)
+}
+div.extra-credit .admonition-title:before {
+ color: rgba(var(--pst-color-success), 1);
+ content: '\f19d';
+}
+```
+
+Then, in your book, define an admonition like so:
+
+````md
+```{admonition} An extra exercise
+:class: extra-credit
+An "extra credit" exercise is presented here.
+```
+````
+
+In both cases the admonitions should be styled according to your CSS rules when you build your book.
+
## Enable Google Analytics
If you have a Google account, you can use Google Analytics to collect some
--
GitLab