1 files changed, 63 insertions, 0 deletions
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`.