diff --git a/doc/code-cells.ipynb b/doc/code-cells.ipynb
index 1d550e22..b4453641 100644
--- a/doc/code-cells.ipynb
+++ b/doc/code-cells.ipynb
@@ -444,6 +444,32 @@
     "fig"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `width`, `height`, and `alt` attributes of the eventual HTML output can be set via cell metadata corresponding to the image format like so:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%config InlineBackend.figure_formats = ['png']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "display(fig, metadata={\"image/png\": {\"width\": \"150px\", \"height\": \"100px\",\n",
+    "                                     \"alt\": \"this is my alt text\"}})"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
diff --git a/src/nbsphinx.py b/src/nbsphinx.py
index dc2d03d5..97476fb7 100644
--- a/src/nbsphinx.py
+++ b/src/nbsphinx.py
@@ -181,7 +181,11 @@
 {%- set height = output.metadata[datatype].height %}
 {%- if height %}
         :height: {{ height }}
-{% endif %}
+{%- endif %}
+{%- set alt = output.metadata[datatype].alt %}
+{%- if alt %}
+        :alt: {{ alt }}
+{%- endif %}
 {% endif %}
 {%- elif datatype in ['text/markdown'] %}