From 8dfef829b868be5e8d8f4d404f1e05dcc8e3542c Mon Sep 17 00:00:00 2001
From: Oleh Prypin <oleh@pryp.in>
Date: Sun, 18 Sep 2022 19:39:23 +0200
Subject: [PATCH] Enable `<details>` admonitions and nested codeblocks

---
 docs/user-guide/configuration.md | 94 ++++++++++++++++----------------
 mkdocs.yml                       |  3 +
 requirements/project-min.txt     |  4 +-
 requirements/project.txt         |  2 +-
 4 files changed, 54 insertions(+), 49 deletions(-)

diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
index f32a26a2..b0b6877a 100644
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -164,38 +164,38 @@ And the conversion flag `!q` is available, to percent-encode the field:
 
 * `{path!q}`, e.g. `foo%2Fbar.md`
 
-Here are some suggested configurations that can be useful:
-
-GitHub Wiki:  
-(e.g. `https://github.com/project/repo/wiki/foo/bar/_edit`)
-
-```yaml
-repo_url: 'https://github.com/project/repo/wiki'
-edit_uri_template: '{path_noext}/_edit'
-```
-
-BitBucket editor:  
-(e.g. `https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit`)
-
-```yaml
-repo_url: 'https://bitbucket.org/project/repo/'
-edit_uri_template: 'src/master/docs/{path}?mode=edit'
-```
-
-GitLab Static Site Editor:  
-(e.g. `https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md`)
-
-```yaml
-repo_url: 'https://gitlab.com/project/repo'
-edit_uri_template: '-/sse/master/docs%2F{path!q}'
-```
-
-GitLab Web IDE:  
-(e.g. `https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md`)
-
-```yaml
-edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}'
-```
+>? NOTE: **Suggested useful configurations:**
+>
+> *   GitHub Wiki:  
+>     (e.g. `https://github.com/project/repo/wiki/foo/bar/_edit`)
+>
+>     ```yaml
+>     repo_url: 'https://github.com/project/repo/wiki'
+>     edit_uri_template: '{path_noext}/_edit'
+>     ```
+>
+> *   BitBucket editor:  
+>     (e.g. `https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit`)
+>
+>     ```yaml
+>     repo_url: 'https://bitbucket.org/project/repo/'
+>     edit_uri_template: 'src/master/docs/{path}?mode=edit'
+>     ```
+>
+> *   GitLab Static Site Editor:  
+>     (e.g. `https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md`)
+>
+>     ```yaml
+>     repo_url: 'https://gitlab.com/project/repo'
+>     edit_uri_template: '-/sse/master/docs%2F{path!q}'
+>     ```
+>
+> *   GitLab Web IDE:  
+>     (e.g. `https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md`)
+>
+>     ```yaml
+>     edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}'
+>     ```
 
 **default**: `null`
 
@@ -599,20 +599,22 @@ def on_page_markdown(markdown, **kwargs):
     return markdown.replace('a', 'z')
 ```
 
-Advanced example that produces warnings based on the Markdown content (and warnings are fatal in [strict](#strict) mode):
-
-```python
-import logging, re
-import mkdocs.plugins
-
-log = logging.getLogger('mkdocs')
-
-@mkdocs.plugins.event_priority(-50)
-def on_page_markdown(markdown, page, **kwargs):
-    path = page.file.src_uri
-    for m in re.finditer(r'\bhttp://[^) ]+', markdown):
-        log.warning(f"Documentation file '{path}' contains a non-HTTPS link: {m[0]}")
-```
+>? EXAMPLE: **Advanced example:**
+>
+> This produces warnings based on the Markdown content (and warnings are fatal in [strict](#strict) mode):
+>
+> ```python
+> import logging, re
+> import mkdocs.plugins
+>
+> log = logging.getLogger('mkdocs')
+>
+> @mkdocs.plugins.event_priority(-50)
+> def on_page_markdown(markdown, page, **kwargs):
+>     path = page.file.src_uri
+>     for m in re.finditer(r'\bhttp://[^) ]+', markdown):
+>         log.warning(f"Documentation file '{path}' contains a non-HTTPS link: {m[0]}")
+> ```
 
 This does not enable any new abilities compared to [plugins][], it only simplifies one-off usages, as these don't need to be *installed* like plugins do.
 
diff --git a/mkdocs.yml b/mkdocs.yml
index c542166d..2c24b56c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -33,7 +33,10 @@ markdown_extensions:
         permalink: 
     - attr_list
     - def_list
+    - pymdownx.highlight:
+        use_pygments: false
     - pymdownx.snippets
+    - pymdownx.superfences
     - callouts
     - mdx_gh_links:
         user: mkdocs
diff --git a/requirements/project-min.txt b/requirements/project-min.txt
index 1dee5c96..33d2c932 100644
--- a/requirements/project-min.txt
+++ b/requirements/project-min.txt
@@ -1,7 +1,7 @@
 click==7.0
 Jinja2==2.11.1
 markupsafe==2.0.1
-Markdown==3.3
+Markdown==3.3.3
 PyYAML==5.1
 watchdog==2.0.0
 ghp-import==1.0
@@ -14,7 +14,7 @@ babel==2.9.0
 
 colorama==0.4; platform_system == 'Windows'
 mdx_gh_links==0.2
-markdown-callouts==0.2
+markdown-callouts==0.3.0
 mkdocs-literate-nav==0.5.0
 mkdocs-redirects==1.0.1
 pymdown-extensions==8.0.1
diff --git a/requirements/project.txt b/requirements/project.txt
index 2a1bf6fa..1b5e3014 100644
--- a/requirements/project.txt
+++ b/requirements/project.txt
@@ -14,7 +14,7 @@ babel>=2.9.0
 
 colorama>=0.4; platform_system == 'Windows'
 mdx_gh_links>=0.2
-markdown-callouts>=0.2
+markdown-callouts>=0.3.0
 mkdocs-literate-nav>=0.5.0
 mkdocs-redirects>=1.0.1
 pymdown-extensions>=8.0.1