Documentation

* Updated images documentation to include pymdownx.blocks.caption extension

* put back HTML figure in image caption docs

* fix typo in image captions

Author: joapuiib

docs/reference/images.md

@@ -19,15 +19,18 @@ following lines to `mkdocs.yml`:
 markdown_extensions:
   - attr_list
   - md_in_html
+  - pymdownx.blocks.caption
 ```
 
 See additional configuration options:
 
 - [Attribute Lists]
 - [Markdown in HTML]
+- [Caption]
 
   [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
   [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+  [Caption]: ../setup/extensions/python-markdown-extensions.md#caption
 
 ### Lightbox
 
@@ -135,6 +138,16 @@ but it's always possible to use the [Markdown in HTML] extension with literal
   </figure>
 </div>
 
+However, [Caption] provides an alternative syntax to add captions
+to any Markdown block element, including images:
+
+``` markdown title="Image with caption"
+![Image title](https://dummyimage.com/600x400/){ width="300" }
+/// caption
+Image caption
+///
+```
+
 ### Image lazy-loading
 
 Modern browsers provide [native support for lazy-loading images][lazy-loading]

docs/setup/extensions/python-markdown-extensions.md

@@ -110,6 +110,25 @@ documentation][BetterEm] for more information.
 
   [BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
 
+### Caption
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [pymdownx.blocks.caption][Caption] -->
+
+The [Caption] extension adds the ability to add captions to any Markdown block,
+including images, tables, and code blocks. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.blocks.caption
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [Caption
+documentation][Caption] for more information.
+
+  [Caption]: https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/
+
 ### Caret, Mark & Tilde
 
 <!-- md:version 1.0.0 -->