[APT-1575] Add support for image captions via plugin

docusaurus.config.js

@@ -5,6 +5,8 @@ const lightCodeTheme = require("prism-react-renderer/themes/github")
 const darkCodeTheme = require("prism-react-renderer/themes/dracula")
 const cfg = require("config")
 
+const captionsPlugin = require("./src/plugins/captions")
+
 const googleAnalyticsConfig = cfg.has("googleAnalytics")
   ? cfg.get("googleAnalytics")
   : undefined
@@ -32,6 +34,7 @@ const config = {
           sidebarPath: require.resolve("./sidebars.js"),
           // Please change this to your repo.
           // editUrl: "https://github.com/facebook/docusaurus/edit/main/website/",
+          beforeDefaultRemarkPlugins: [captionsPlugin],
         },
         theme: {
           customCss: require.resolve("./src/css/custom.css"),

src/css/custom.css

@@ -69,6 +69,22 @@ main {
   margin-top: 2em;
 }
 
+/* IMAGES & CAPTIONS */
+
+p > img {
+  display: block;
+  margin: auto;
+}
+
+p > img + em {
+  color: gray;
+  font-size: 0.9rem;
+  display: block;
+  text-align: center;
+  max-width: 80%;
+  margin: 1rem auto 2rem auto;
+}
+
 /* HOME PAGE */
 
 .hero--primary .button--lg {

src/plugins/captions.js

@@ -0,0 +1,51 @@
+const visit = require("unist-util-visit")
+
+// This plugin repurposes the alt text specified for images to
+// automatically generate captions for them. For example:
+//
+// ![This alt text will also appear as a caption](/img/example.png)
+//
+// The caption is injected as an <em> element in the output, which can
+// then be styled using an `img + em` selector.
+//
+// Note that it's also possible to override the automated behavior
+// of this plugin by proving a custom caption in an emphasis block
+// immediately following the image in the markdown, e.g.
+//
+// ![Alt text, overridden by the caption below](/img/example.png)
+// _A custom caption, which overrides the alt text above_
+
+const plugin = (options) => {
+  const transformer = async (ast) => {
+    visit(ast, "paragraph", (node) => {
+      if (
+        node.children &&
+        node.children.length === 1 && // exactly one child
+        node.children[0].type === "image" && // that is an image
+        node.children[0].alt // with a specified alt attribute
+      ) {
+        // Replace the existing paragraph node with a newly
+        // constructed one which contains the original image node
+        // and a new emphasis node containing its alt text.
+        return Object.assign(node, {
+          type: "paragraph",
+          children: [
+            node.children[0],
+            {
+              type: "emphasis",
+              children: [
+                {
+                  type: "text",
+                  value: node.children[0].alt,
+                },
+              ],
+            },
+          ],
+        })
+      }
+    })
+  }
+  return transformer
+}
+
+module.exports = plugin