diff --git a/docs/_quarto.yml b/docs/_quarto.yml
index 0b5918e..5406ba2 100644
--- a/docs/_quarto.yml
+++ b/docs/_quarto.yml
@@ -20,9 +20,15 @@ website:
   title: "Code Window"
   description: "A Quarto filter that dresses code blocks as application windows, with a filename, traffic lights, and optional folding."
   # No trailing slash: Quarto builds the social image URL by concatenating this
-  # with a leading-slash image path, without normalising.
+  # with the image path, without normalising.
   site-url: &site-url https://m.canouil.dev/quarto-code-window
   repo-url: https://github.com/mcanouil/quarto-code-window
+  open-graph:
+    image: assets/social/og-image.png
+    image-alt: "The quarto-code-window social card: the extension name and the \"filter\" badge over the line \"Style code blocks as macOS-style windows with title bars\", beside a dark code window showing document.qmd."
+  twitter-card:
+    image: assets/social/og-image.png
+    image-alt: "The quarto-code-window social card: the extension name and the \"filter\" badge over the line \"Style code blocks as macOS-style windows with title bars\", beside a dark code window showing document.qmd."
   # The Quarto project root is `docs/`, so without this every edit and issue
   # link points at a path one level up from the page it was built for.
   repo-subdir: docs
diff --git a/docs/assets/social/README.md b/docs/assets/social/README.md
new file mode 100644
index 0000000..19304c9
--- /dev/null
+++ b/docs/assets/social/README.md
@@ -0,0 +1,25 @@
+# Social card
+
+`og-image.png` is the Open Graph preview for this site, 1200x630, referenced from
+`website.open-graph.image` and `website.twitter-card.image` in `_quarto.yml`.
+The keys sit inside those two blocks because that is the only form that beats Quarto's own
+first-image harvest. A project-level `website.image` loses to that harvest on any page whose
+first inline image is a data URI, which is what this site served as `og:image` before.
+
+It is not authored here.
+The card comes from [quarto-social-cards](https://github.com/mcanouil/quarto-social-cards), a Typst
+template that renders one card per Quarto extension.
+The catalogue entry for this extension is the `#social-card(...)` block with
+`extension-name: "code-window"`.
+
+To regenerate, run `./export-cards.sh` in that repository, then resize its output into this
+directory:
+
+```bash
+magick social-cards/quarto-code-window.png -resize 1200x630 -alpha off -strip \
+  -define png:compression-level=9 og-image.png
+```
+
+`export-cards.sh` renders the 1200x630 design at 144 PPI, so the exported PNG is 2400x1260.
+The resize brings it back to the design size, which is what Open Graph consumers expect and what
+`og:image:width` and `og:image:height` report.
diff --git a/docs/assets/social/og-image.png b/docs/assets/social/og-image.png
new file mode 100644
index 0000000..5b93668
Binary files /dev/null and b/docs/assets/social/og-image.png differ