Added support and documentation for image alignment and captions

docs/reference/images.md

@@ -0,0 +1,89 @@
+---
+template: overrides/main.html
+---
+
+# Images
+
+While images are first-class citizens of Markdown and part of the core syntax, 
+it can be difficult to work with them. Material for MkDocs makes working with 
+images more comfortable by providing styles for alignment and image captions.
+
+  [1]: https://www.markdownguide.org/basic-syntax/#images-1
+
+## Configuration
+
+### Attribute List
+
+The [Attribute List][2] extension, which is part of the standard Markdown
+library, allows to __add HTML attributes and CSS classes to Markdown elements__,
+and can be enabled via `mkdocs.yml`
+
+``` yaml
+markdown_extensions:
+  - attr_list
+```
+
+  [2]: https://python-markdown.github.io/extensions/attr_list/
+
+## Usage
+
+### Image alignment
+
+When the [Attribute List][2] extension is enabled, images can be aligned by
+adding the respective alignment directions via the `align` attribute, i.e.
+`align=left` or `align=right`
+
+=== "Left"
+
+    _Example_:
+
+    ``` markdown
+    ![Placeholder](https://dummyimage.com/600x400/eee/aaa){ align=left }
+    ```
+
+    _Result_:
+
+    ![Placeholder](https://dummyimage.com/600x400/eee/aaa){ align=left width=300 }
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+=== "Right"
+
+    _Example_:
+
+    ``` markdown
+    ![Placeholder](https://dummyimage.com/600x400/eee/aaa){ align=right }
+    ```
+
+    _Result_:
+
+    ![Placeholder](https://dummyimage.com/600x400/eee/aaa){ align=right width=300 }
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+_If there's insufficient space to render the text next to the image, the image
+will stretch to the full width of the viewport, e.g. on mobile viewports._
+
+### Image captions
+
+Sadly, the Markdown syntax doesn't provide native support for image captions,
+but it's always possible to resort to HTML. Using `figure` and `figcaption`, captions can be added to images.
+
+_Example_:
+
+```html
+<figure>
+  <img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
+  <figcaption>Image caption</figcaption>
+</figure>
+```
+
+_Result_:
+<figure>
+  <img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
+  <figcaption>Image caption</figcaption>
+</figure>

material/assets/manifest.json

@@ -5,10 +5,10 @@
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.877163d5.min.js.map",
   "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.1b3b2620.min.js",
   "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.1b3b2620.min.js.map",
-  "assets/stylesheets/main.css": "assets/stylesheets/main.5be48db2.min.css",
+  "assets/stylesheets/main.css": "assets/stylesheets/main.a0d075aa.min.css",
-  "assets/stylesheets/main.css.map": "assets/stylesheets/main.5be48db2.min.css.map",
+  "assets/stylesheets/main.css.map": "assets/stylesheets/main.a0d075aa.min.css.map",
   "assets/stylesheets/overrides.css": "assets/stylesheets/overrides.5036298b.min.css",
   "assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.5036298b.min.css.map",
-  "assets/stylesheets/palette.css": "assets/stylesheets/palette.89d31e3b.min.css",
+  "assets/stylesheets/palette.css": "assets/stylesheets/palette.0ec9b792.min.css",
-  "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.89d31e3b.min.css.map"
+  "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.0ec9b792.min.css.map"
 }

material/base.html

@@ -41,9 +41,9 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.5be48db2.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.a0d075aa.min.css' | url }}">
       {% if palette.scheme or palette.primary or palette.accent %}
-        <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.89d31e3b.min.css' | url }}">
+        <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.0ec9b792.min.css' | url }}">
       {% endif %}
       {% if palette.primary %}
         {% import "partials/palette.html" as map %}

mkdocs.yml

@@ -171,6 +171,7 @@ nav:
     - Footnotes: reference/footnotes.md
     - Formatting: reference/formatting.md
     - Icons + Emojis: reference/icons-emojis.md
+    - Images: reference/images.md
     - Lists: reference/lists.md
     - MathJax: reference/mathjax.md
     - Meta tags: reference/meta-tags.md

src/assets/stylesheets/main/_typeset.scss

@@ -389,6 +389,38 @@ kbd {
   svg {
     max-width: 100%;
     height: auto;
+
+    // Left-aligned
+    &[align="left"] {
+      margin: 1em;
+      margin-left: 0;
+    }
+
+    // Right-aligned
+    &[align="right"] {
+      margin: 1em;
+      margin-right: 0;
+    }
+
+    // Remove top spacing of sole children
+    &[align]:only-child {
+      margin-top: 0;
+    }
+  }
+
+  // Figures
+  figure {
+    width: fit-content;
+    max-width: 100%;
+    margin: 0 auto;
+    text-align: center;
+  }
+
+  // Figure captions
+  figcaption {
+    max-width: px2rem(480px);
+    margin: 0.5em auto;
+    font-style: italic;
   }
 
   // Limit width to container