From 2fc36e151300550b155fe37713429e365e8ec776 Mon Sep 17 00:00:00 2001
From: Dennis Fink
Date: Thu, 23 Jul 2026 00:19:28 +0200
Subject: Add Markdown figure support

This adds a project-local Markdown figure plugin so blog posts can use
semantic `<figure>` blocks with arbitrary CSS classes, optional
captions, and Markdown inside captions.

The image CSS is also updated so figures share the existing width,
breakout, float, centering, and rounded-image utilities while keeping
captions styled and spaced consistently with the rest of the article
layout.
---
 packages/markdown-figure/README.md | 63 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 packages/markdown-figure/README.md

(limited to 'packages/markdown-figure/README.md')

diff --git a/packages/markdown-figure/README.md b/packages/markdown-figure/README.md
new file mode 100644
index 0000000..a063f3c
--- /dev/null
+++ b/packages/markdown-figure/README.md
@@ -0,0 +1,63 @@
+# Lektor Markdown Figure
+
+A project-local Lektor plugin providing semantic Markdown figures with:
+
+- any whitespace-separated CSS classes;
+- an optional caption;
+- Markdown parsing inside the caption;
+- Lektor's normal attachment-relative image URL resolution.
+
+## Installation
+
+Place this directory at:
+
+```text
+packages/markdown-figure/
+```
+
+Restart `lektor server` after adding it.
+
+## Syntax
+
+```markdown
+:::figure right w50 breakout-sm
+![Alternative text](example.jpg "Optional image title")
+
+A caption with *emphasis*, **strong text**, [links](https://example.com/),
+and other Markdown.
+:::
+```
+
+The first non-empty line must be the Markdown image. Everything after that is
+the optional caption.
+
+Without a caption:
+
+```markdown
+:::figure center w75
+![Alternative text](example.jpg)
+:::
+```
+
+This produces no `<figcaption>` element.
+
+## Output
+
+```html
+<figure class="right w50 breakout-sm">
+  <img src="example.jpg" alt="Alternative text" title="Optional image title">
+  <figcaption>
+    <p>A caption with <em>emphasis</em>, …</p>
+  </figcaption>
+</figure>
+```
+
+The class names are not allow-listed or transformed. They are copied to the
+`class` attribute after HTML escaping and whitespace normalisation.
+
+## Notes
+
+- The opening marker is `:::figure`, followed by zero or more CSS classes.
+- The closing marker is `:::` on its own line.
+- Nested figure directives inside captions are intentionally not parsed.
+- A matched figure block whose first content line is not an image fails with a clear `ValueError`.
-- 
cgit v1.3.1