From: Vladimír Vondruš <mosra@centrum.cz>
Date: Tue, 4 Jan 2022 18:54:09 +0000 (+0100)
Subject: css: work around Firefox-specific behavior with .m-figure.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=b04d3d30db165ac155ab64720851302ff17e4266;p=blog.git

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 efbefb11..651426f7 100644
--- 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 f6ce4a44..838942f4 100644
--- 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 2bc81103..94396a52 100644
--- 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 939c1342..d773c9c3 100644
--- 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 97474a8c..31afd8fb 100644
--- 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 a65e5606..b2fb15d0 100644
--- 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 62cec545..64f1bf10 100644
--- 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`_