packages/markdown-figure/README.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
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`.