css: work around Firefox-specific behavior with .m-figure.

The `.m-figure > *` has `display: table-caption;` to make overlong
content wrap to width of the image, instead of pushing out the figure
border. However, this makes Firefox render just the first element and
ignore everything after, thus the original figure descriptions weren't
visible in Firefox, only in Chrome.

Because HTML5 says <figcaption> has to be right inside <figure>, I can't
wrap the caption together with other content in a <span>, although that
would make Firefox render things properly. Instead I'm nesting all
description inside <figcaption> in a .m-figure-description, which then
reverts all styling applied for <figcaption>. Kinda ew, but works.

Originally this was reported for just image figures, but the same
problem applies to math and graph figures as well. Not for code/console
figure though, as those don't have `display: table-caption;` and instead
span the whole width always.

This has to be fixed in m.htmlsanity as well, doing that in a separate
commit as it's a bit involved as well.

diff --git a/css/m-components.css b/css/m-components.css
index efbefb1172e38af53cb0b51542716489b140dbb8..651426f7fbfef269fe69d0c1963f639f3e793c13 100644 (file)
--- a/css/m-components.css
+++ b/css/m-components.css
@@ -538,6 +538,8 @@ figure.m-figure.m-flat:before {
 figure.m-figure > * {
   margin-left: 1rem;
   margin-right: 1rem;
+  /* So overflowing figcaption or any other content doesn't expand the figure
+     border but rather gets wrapped */
   display: table-caption;
   caption-side: bottom;
 }
@@ -644,6 +646,21 @@ figure.m-figure figcaption, .m-code-figure figcaption, .m-console-figure figcapt
 figure.m-figure figcaption a, .m-code-figure figcaption a, .m-console-figure figcaption a {
   text-decoration: var(--link-decoration-heading);
 }
+/* Figure description, expected to be inside <figcaption> and has all styling
+   from <figcaption> reverted. Originally this was done by adding a <span>
+   after <figcaption> but while fine in Chrome, the `display: table-caption;`
+   for everything in <figure> made Firefox render just the <figcaption>,
+   ignoring everything after that. So it has to be all inside <figcaption>. See
+   also https://github.com/mosra/m.css/issues/117 for details. */
+figure.m-figure figcaption .m-figure-description {
+  display: block;
+  margin-top: 0.5rem;
+  font-weight: normal;
+  font-size: 1rem;
+}
+figure.m-figure figcaption .m-figure-description a {
+  text-decoration: var(--link-decoration);
+}
 
 /* Image grid */
 .m-imagegrid > div {
@@ -1277,14 +1294,19 @@ figure.m-figure.m-default:before { border-color: var(--default-filled-background
 figure.m-figure.m-default figcaption { color: var(--default-color); }
 figure.m-figure.m-primary:before { border-color: var(--primary-filled-background-color); }
 figure.m-figure.m-primary figcaption { color: var(--primary-color); }
+figure.m-figure.m-primary figcaption .m-figure-description { color: var(--default-color); }
 figure.m-figure.m-success:before { border-color: var(--success-filled-background-color); }
 figure.m-figure.m-success figcaption { color: var(--success-color); }
+figure.m-figure.m-success figcaption .m-figure-description { color: var(--default-color); }
 figure.m-figure.m-warning:before { border-color: var(--warning-filled-background-color); }
 figure.m-figure.m-warning figcaption { color: var(--warning-color); }
+figure.m-figure.m-warning figcaption .m-figure-description { color: var(--default-color); }
 figure.m-figure.m-danger:before { border-color: var(--danger-filled-background-color); }
 figure.m-figure.m-danger figcaption { color: var(--danger-color); }
+figure.m-figure.m-danger figcaption .m-figure-description { color: var(--default-color); }
 figure.m-figure.m-info:before { border-color: var(--info-filled-background-color); }
 figure.m-figure.m-info figcaption { color: var(--info-color); }
+figure.m-figure.m-info figcaption .m-figure-description { color: var(--default-color); }
 figure.m-figure.m-dim:before { border-color: var(--dim-filled-background-color); }
 figure.m-figure.m-dim { color: var(--dim-color); }
 figure.m-figure.m-dim a { color: var(--dim-link-color); }

diff --git a/css/m-dark+documentation.compiled.css b/css/m-dark+documentation.compiled.css
index f6ce4a446e45f4a87f06f829f528a7ae9b4cb69f..838942f479761dc423094b1a88a42cde4b7ea5c8 100644 (file)
--- a/css/m-dark+documentation.compiled.css
+++ b/css/m-dark+documentation.compiled.css
@@ -901,6 +901,15 @@ figure.m-figure figcaption, .m-code-figure figcaption, .m-console-figure figcapt
 figure.m-figure figcaption a, .m-code-figure figcaption a, .m-console-figure figcaption a {
   text-decoration: none;
 }
+figure.m-figure figcaption .m-figure-description {
+  display: block;
+  margin-top: 0.5rem;
+  font-weight: normal;
+  font-size: 1rem;
+}
+figure.m-figure figcaption .m-figure-description a {
+  text-decoration: underline;
+}
 .m-imagegrid > div {
   background-color: #2f363f;
 }
@@ -1493,14 +1502,19 @@ figure.m-figure.m-default:before { border-color: #34424d; }
 figure.m-figure.m-default figcaption { color: #dcdcdc; }
 figure.m-figure.m-primary:before { border-color: #a5c2db; }
 figure.m-figure.m-primary figcaption { color: #a5c9ea; }
+figure.m-figure.m-primary figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-success:before { border-color: #2a703f; }
 figure.m-figure.m-success figcaption { color: #3bd267; }
+figure.m-figure.m-success figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-warning:before { border-color: #6d702a; }
 figure.m-figure.m-warning figcaption { color: #c7cf2f; }
+figure.m-figure.m-warning figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-danger:before { border-color: #702b2a; }
 figure.m-figure.m-danger figcaption { color: #cd3431; }
+figure.m-figure.m-danger figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-info:before { border-color: #2a4f70; }
 figure.m-figure.m-info figcaption { color: #2f83cc; }
+figure.m-figure.m-info figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-dim:before { border-color: #2d3236; }
 figure.m-figure.m-dim { color: #747474; }
 figure.m-figure.m-dim a { color: #acacac; }

diff --git a/css/m-dark.compiled.css b/css/m-dark.compiled.css
index 2bc8110371a422c703e2e5c49b473e9f36b42805..94396a52dc1db83415463f65250013d64bc13001 100644 (file)
--- a/css/m-dark.compiled.css
+++ b/css/m-dark.compiled.css
@@ -901,6 +901,15 @@ figure.m-figure figcaption, .m-code-figure figcaption, .m-console-figure figcapt
 figure.m-figure figcaption a, .m-code-figure figcaption a, .m-console-figure figcaption a {
   text-decoration: none;
 }
+figure.m-figure figcaption .m-figure-description {
+  display: block;
+  margin-top: 0.5rem;
+  font-weight: normal;
+  font-size: 1rem;
+}
+figure.m-figure figcaption .m-figure-description a {
+  text-decoration: underline;
+}
 .m-imagegrid > div {
   background-color: #2f363f;
 }
@@ -1493,14 +1502,19 @@ figure.m-figure.m-default:before { border-color: #34424d; }
 figure.m-figure.m-default figcaption { color: #dcdcdc; }
 figure.m-figure.m-primary:before { border-color: #a5c2db; }
 figure.m-figure.m-primary figcaption { color: #a5c9ea; }
+figure.m-figure.m-primary figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-success:before { border-color: #2a703f; }
 figure.m-figure.m-success figcaption { color: #3bd267; }
+figure.m-figure.m-success figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-warning:before { border-color: #6d702a; }
 figure.m-figure.m-warning figcaption { color: #c7cf2f; }
+figure.m-figure.m-warning figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-danger:before { border-color: #702b2a; }
 figure.m-figure.m-danger figcaption { color: #cd3431; }
+figure.m-figure.m-danger figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-info:before { border-color: #2a4f70; }
 figure.m-figure.m-info figcaption { color: #2f83cc; }
+figure.m-figure.m-info figcaption .m-figure-description { color: #dcdcdc; }
 figure.m-figure.m-dim:before { border-color: #2d3236; }
 figure.m-figure.m-dim { color: #747474; }
 figure.m-figure.m-dim a { color: #acacac; }

diff --git a/css/m-light+documentation.compiled.css b/css/m-light+documentation.compiled.css
index 939c1342eab70bbee5263e1109de12a0f40ba238..d773c9c3c45ed3c885429a3f8fcf0339925679ae 100644 (file)
--- a/css/m-light+documentation.compiled.css
+++ b/css/m-light+documentation.compiled.css
@@ -901,6 +901,15 @@ figure.m-figure figcaption, .m-code-figure figcaption, .m-console-figure figcapt
 figure.m-figure figcaption a, .m-code-figure figcaption a, .m-console-figure figcaption a {
   text-decoration: none;
 }
+figure.m-figure figcaption .m-figure-description {
+  display: block;
+  margin-top: 0.5rem;
+  font-weight: normal;
+  font-size: 1rem;
+}
+figure.m-figure figcaption .m-figure-description a {
+  text-decoration: underline;
+}
 .m-imagegrid > div {
   background-color: #ffffff;
 }
@@ -1493,14 +1502,19 @@ figure.m-figure.m-default:before { border-color: #fbf0ec; }
 figure.m-figure.m-default figcaption { color: #000000; }
 figure.m-figure.m-primary:before { border-color: #ef9069; }
 figure.m-figure.m-primary figcaption { color: #cb4b16; }
+figure.m-figure.m-primary figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-success:before { border-color: #4dd376; }
 figure.m-figure.m-success figcaption { color: #31c25d; }
+figure.m-figure.m-success figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-warning:before { border-color: #d1d34d; }
 figure.m-figure.m-warning figcaption { color: #c7cf2f; }
+figure.m-figure.m-warning figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-danger:before { border-color: #e23e3e; }
 figure.m-figure.m-danger figcaption { color: #f60000; }
+figure.m-figure.m-danger figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-info:before { border-color: #4c93d3; }
 figure.m-figure.m-info figcaption { color: #2e7dc5; }
+figure.m-figure.m-info figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-dim:before { border-color: #f1f1f1; }
 figure.m-figure.m-dim { color: #bdbdbd; }
 figure.m-figure.m-dim a { color: #c0c0c0; }

diff --git a/css/m-light.compiled.css b/css/m-light.compiled.css
index 97474a8cd56404f3387a083c02d6917741bfa0f1..31afd8fb39e9ef6562218ad27f1f16625644de94 100644 (file)
--- a/css/m-light.compiled.css
+++ b/css/m-light.compiled.css
@@ -901,6 +901,15 @@ figure.m-figure figcaption, .m-code-figure figcaption, .m-console-figure figcapt
 figure.m-figure figcaption a, .m-code-figure figcaption a, .m-console-figure figcaption a {
   text-decoration: none;
 }
+figure.m-figure figcaption .m-figure-description {
+  display: block;
+  margin-top: 0.5rem;
+  font-weight: normal;
+  font-size: 1rem;
+}
+figure.m-figure figcaption .m-figure-description a {
+  text-decoration: underline;
+}
 .m-imagegrid > div {
   background-color: #ffffff;
 }
@@ -1493,14 +1502,19 @@ figure.m-figure.m-default:before { border-color: #fbf0ec; }
 figure.m-figure.m-default figcaption { color: #000000; }
 figure.m-figure.m-primary:before { border-color: #ef9069; }
 figure.m-figure.m-primary figcaption { color: #cb4b16; }
+figure.m-figure.m-primary figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-success:before { border-color: #4dd376; }
 figure.m-figure.m-success figcaption { color: #31c25d; }
+figure.m-figure.m-success figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-warning:before { border-color: #d1d34d; }
 figure.m-figure.m-warning figcaption { color: #c7cf2f; }
+figure.m-figure.m-warning figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-danger:before { border-color: #e23e3e; }
 figure.m-figure.m-danger figcaption { color: #f60000; }
+figure.m-figure.m-danger figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-info:before { border-color: #4c93d3; }
 figure.m-figure.m-info figcaption { color: #2e7dc5; }
+figure.m-figure.m-info figcaption .m-figure-description { color: #000000; }
 figure.m-figure.m-dim:before { border-color: #f1f1f1; }
 figure.m-figure.m-dim { color: #bdbdbd; }
 figure.m-figure.m-dim a { color: #c0c0c0; }

diff --git a/doc/css/components-test.rst b/doc/css/components-test.rst
index a65e5606363b2e9eb7592f156aa88acac9b70784..b2fb15d0f0ceffd2eae75a3171deeafb438d97fa 100644 (file)
--- a/doc/css/components-test.rst
+++ b/doc/css/components-test.rst
@@ -1011,8 +1011,11 @@ Figure, centered:
 
     <figure class="m-figure">
       <img src="{static}/static/ship-small.jpg" />
-      <figcaption>A Ship</figcaption>
-      <span>Photo © <a href="http://blog.mosra.cz/">The Author</a></span>
+      <figcaption>
+        A Ship
+        <span class="m-figure-description">Photo ©
+        <a href="http://blog.mosra.cz/">The Author</a></span>
+      </figcaption>
     </figure>
 
 Figure, centered, image link, flat:
@@ -1021,8 +1024,11 @@ Figure, centered, image link, flat:
 
     <figure class="m-figure m-flat">
       <a href="http://blog.mosra.cz/"><img src="{static}/static/ship-small.jpg" /></a>
-      <figcaption>A Ship</figcaption>
-      <span>Photo © <a href="http://blog.mosra.cz/">The Author</a></span>
+      <figcaption>
+        A Ship
+        <span class="m-figure-description">Photo ©
+        <a href="http://blog.mosra.cz/">The Author</a></span>
+      </figcaption>
     </figure>
 
 Figure, fullwidth, without description (yes, it should be pixelated):
@@ -1041,10 +1047,13 @@ unnecessary wrapping of the text:
 
     <figure class="m-figure m-fullwidth">
       <img src="{static}/static/ship-small.jpg" />
-      <figcaption>A Somewhat Lengthy Caption For A Photo</figcaption>
-      <span>The Photo Displayed Above Was Kindly Taken And Allowed To Be Used
-      On This Page By <a href="http://blog.mosra.cz/">The Author</a>. All
-      Rights Reserved.</span>
+      <figcaption>
+        A Somewhat Lengthy Caption For A Photo
+        <span class="m-figure-description">The Photo Displayed Above Was Kindly
+        Taken And Allowed To Be Used On This Page By
+        <a href="http://blog.mosra.cz/">The Author</a>. All Rights
+        Reserved.</span>
+      </figcaption>
     </figure>
 
 Figure with a large image but not fullwidth, should look the same as above, no
@@ -1054,10 +1063,13 @@ leaking of the image outside of the page:
 
     <figure class="m-figure">
       <img src="{static}/static/ship.jpg" />
-      <figcaption>A Somewhat Lengthy Caption For A Photo</figcaption>
-      <span>The Photo Displayed Above Was Kindly Taken And Allowed To Be Used
-      On This Page By <a href="http://blog.mosra.cz/">The Author</a>. All
-      Rights Reserved.</span>
+      <figcaption>
+        A Somewhat Lengthy Caption For A Photo
+        <span class="m-figure-description">The Photo Displayed Above Was Kindly
+        Taken And Allowed To Be Used On This Page By
+        <a href="http://blog.mosra.cz/">The Author</a>. All Rights
+        Reserved.</span>
+      </figcaption>
     </figure>
 
 Figure with a long caption and description, then just a caption (it should wrap
@@ -1067,10 +1079,13 @@ instead of extending the border and there should be proper padding on bottom):
 
     <figure class="m-figure">
       <img src="{static}/static/ship-small.jpg" />
-      <figcaption>A Somewhat Lengthy Caption For A Photo</figcaption>
-      <span>The Photo Displayed Above Was Kindly Taken And Allowed To Be Used
-      On This Page By <a href="http://blog.mosra.cz/">The Author</a>. All
-      Rights Reserved.</span>
+      <figcaption>
+        A Somewhat Lengthy Caption For A Photo
+        <span class="m-figure-description">The Photo Displayed Above Was Kindly
+        Taken And Allowed To Be Used On This Page By
+        <a href="http://blog.mosra.cz/">The Author</a>. All Rights
+        Reserved.</span>
+      </figcaption>
     </figure>
 
 .. raw:: html
@@ -1088,29 +1103,37 @@ Figures of varying colors:
       <div class="m-col-m-3 m-col-s-6">
         <figure class="m-figure m-default">
           <img src="{static}/static/ship-small.jpg" />
-          <figcaption>Default figure</figcaption>
-          <span>Text.</span>
+          <figcaption>
+            Default figure
+            <span class="m-figure-description">Text.</span>
+          </figcaption>
         </figure>
       </div>
       <div class="m-col-m-3 m-col-s-6">
         <figure class="m-figure m-primary">
           <img src="{static}/static/ship-small.jpg" />
-          <figcaption>Primary figure</figcaption>
-          <span>Text.</span>
+          <figcaption>
+            Primary figure
+            <span class="m-figure-description">Text.</span>
+          </figcaption>
         </figure>
       </div>
       <div class="m-col-m-3 m-col-s-6">
         <figure class="m-figure m-success">
           <img src="{static}/static/ship-small.jpg" />
-          <figcaption>Success figure</figcaption>
-          <span>Text.</span>
+          <figcaption>
+            Success figure
+            <span class="m-figure-description">Text.</span>
+          </figcaption>
         </figure>
       </div>
       <div class="m-col-m-3 m-col-s-6">
         <figure class="m-figure m-warning">
           <img src="{static}/static/ship-small.jpg" />
-          <figcaption>Warning figure</figcaption>
-          <span>Text.</span>
+          <figcaption>
+            Warning figure
+            <span class="m-figure-description">Text.</span>
+          </figcaption>
         </figure>
       </div>
     </div>
@@ -1118,22 +1141,28 @@ Figures of varying colors:
       <div class="m-col-m-3 m-col-s-6">
         <figure class="m-figure m-danger">
           <img src="{static}/static/ship-small.jpg" />
-          <figcaption>Danger figure</figcaption>
-          <span>Text.</span>
+          <figcaption>
+            Danger figure
+            <span class="m-figure-description">Text.</span>
+          </figcaption>
         </figure>
       </div>
       <div class="m-col-m-3 m-col-s-6">
         <figure class="m-figure m-info">
           <img src="{static}/static/ship-small.jpg" />
-          <figcaption>Info figure</figcaption>
-          <span>Text.</span>
+          <figcaption>
+            Info figure
+            <span class="m-figure-description">Text.</span>
+          </figcaption>
         </figure>
       </div>
       <div class="m-col-m-3 m-col-s-6">
         <figure class="m-figure m-dim">
           <img src="{static}/static/ship-small.jpg" />
-          <figcaption>Dim figure</figcaption>
-          <span>Text.</span>
+          <figcaption>
+            Dim figure
+            <span class="m-figure-description">Text.</span>
+          </figcaption>
         </figure>
       </div>
     </div>

diff --git a/doc/css/components.rst b/doc/css/components.rst
index 62cec545e75f85027148c36bd0fb3e693ece9ee0..64f1bf1090091c80f1e7b5f1d5ba36e223d96f45 100644 (file)
--- a/doc/css/components.rst
+++ b/doc/css/components.rst
@@ -664,8 +664,8 @@ together with :css:`.m-image` will make the image round. Works for both plain
 Use the HTML5 :html:`<figure>` tag together with :css:`.m-figure` to style it.
 As with plain image, it's by default centered, slightly rounded and has a
 border around the caption and description. The caption is expected to be in the
-:html:`<figcaption>` element. The description is optional, but should be
-wrapped in some tag as well (for example a :html:`<span>`). The
+:html:`<figcaption>` element. Inside it, there can optionally be a longer
+description wrapped in a :css:`.m-figure-description` element. The
 :css:`.m-fullwidth` class works here too and you can also wrap the
 :html:`<img>` / :html:`<svg>` element in an :html:`<a>` tag to make it
 clickable.
@@ -673,8 +673,9 @@ clickable.
 Figure always expects at least the caption to be present. If you want just an
 image, use the plain image tag. If you have a lot of figures on the page and
 the border is distracting, apply the :css:`.m-flat` class to hide it.
-Optionally you can color the figure border and caption by adding one of the
-`CSS color classes <#colors>`_ to the :html:`<figure>` element.
+Optionally you can color the figure border and caption (with the description
+staying unaffected) by adding one of the `CSS color classes <#colors>`_ to the
+:html:`<figure>` element.
 
 .. code-figure::
 
@@ -682,16 +683,40 @@ Optionally you can color the figure border and caption by adding one of the
 
         <figure class="m-figure">
           <img src="ship.jpg" alt="Ship" />
-          <figcaption>A Ship</figcaption>
-          <span>Photo © <a href="http://blog.mosra.cz/">The Author</a></span>
+          <figcaption>
+            A Ship
+            <span class="m-figure-description">
+              Photo © <a href="http://blog.mosra.cz/">The Author</a>
+            </span>
+          </figcaption>
         </figure>
 
     .. raw:: html
 
         <figure class="m-figure">
           <img src="{static}/static/ship-small.jpg" alt="Ship" />
+          <figcaption>
+            A Ship
+            <span class="m-figure-description">
+              Photo © <a href="http://blog.mosra.cz/">The Author</a>
+            </span>
+          </figcaption>
+        </figure>
+
+.. note-danger:: Firefox-specific behavior
+
+    While a description *could* be put also after a :html:`<figcaption>` such
+    as in the following snippet, CSS styling used by m.css causes Firefox to
+    display only the :html:`<figcaption>`, ignoring everything after. Thus it's
+    recommended to always nest the description in a :css:`.m-figure-description`
+    element inside. See also :gh:`mosra/m.css#117` for more information.
+
+    .. code:: html
+
+        <figure class="m-figure">
+          <img src="ship.jpg" alt="Ship" />
           <figcaption>A Ship</figcaption>
-          <span>Photo © <a href="http://blog.mosra.cz/">The Author</a></span>
+          <span>Photo © The Author</span> <!-- This will get ignored by Firefox! -->
         </figure>
 
 .. note-info::
@@ -1131,8 +1156,9 @@ Similarly to `code figure`_, math can be also put in a :html:`<figure>` with
 assigned caption and description. It behaves the same as `image figures`_, the
 figure width being defined by the math equation size. Create a
 :html:`<figure class="m-figure">` element and put :html:`<svg class="m-math">`
-as a first child. The remaining content of the figure can be :html:`<figcaption>`
-and/or arbitrary other markup. Add the :css:`.m-flat` class to the
+as a first child. The remaining content of the figure can be
+:html:`<figcaption>` with optional :css:`.m-figure-description` same as with
+`image figures <#figures>`_. Add the :css:`.m-flat` class to the
 :html:`<figure>` to remove the outer border and equation background,
 `CSS color classes`_ on the :html:`<figure>` affect the figure, on the
 :html:`<svg>` affect the equation.
@@ -1146,7 +1172,10 @@ and/or arbitrary other markup. Add the :css:`.m-flat` class to the
             <title>a^2 = b^2 + c^2</title>
             <g>...</g>
           </svg>
-          <figcaption>Pythagorean theorem</figcaption>
+          <figcaption>
+            Theorem
+            <span class="m-figure-description">A Pythagorean one.</span>
+          </figcaption>
         </figure>
 
     .. raw:: html
@@ -1173,7 +1202,10 @@ and/or arbitrary other markup. Add the :css:`.m-flat` class to the
               <use x='219.8' xlink:href='#math1-g1-50' y='-5.84939'/>
             </g>
           </svg>
-          <figcaption>Pythagorean theorem</figcaption>
+          <figcaption>
+            Theorem
+            <span class="m-figure-description">A Pythagorean one.</span>
+          </figcaption>
         </figure>
 
 `Plots`_
@@ -1300,7 +1332,8 @@ on a :css:`.m-node` to make it just an outline instead of filled.
 
 Similarly to `math figure`_, graphs also can be :html:`<figure>`\ s. The
 behavior is almost identical, create a :html:`<figure class="m-figure m-graph">`
-element and put the :html:`<svg>` as a first child, all other content after.
+element and put the :html:`<svg>` as a first child and a :html:`<figcaption>`
+right after.
 
 .. code-figure::
 
@@ -1310,7 +1343,10 @@ element and put the :html:`<svg>` as a first child, all other content after.
           <svg class="m-graph m-warning">
             ...
           </svg>
-          <figcaption>Impenetrable logic</figcaption>
+          <figcaption>
+            Impenetrable logic
+            <span class="m-figure-description">No.</span>
+          </figcaption>
         </figure>
 
     .. raw:: html
@@ -1343,7 +1379,10 @@ element and put the :html:`<svg>` as a first child, all other content after.
         </g>
         </g>
         </svg>
-        <figcaption>Impenetrable logic</figcaption>
+        <figcaption>
+          Impenetrable logic
+          <span class="m-figure-description">No.</span>
+        </figcaption>
         </figure>
 
 `Padding and floating`_