Feature request: custom expander for figures

[jmert]

It'd be nice to add a custom expander which generates HTML <figure><img><figcaption></figcaption></figure> and LaTeX \begin{figure}\includegraphics{}\caption{}\end{figure} blocks. As far as I have been able to find, there's no standard Markdown syntax for this, so I think it'd have to be a custom extension.

So far, I've used a construct that looks like:

```@raw html
<figure>
```
![sphere angles](sphereangles.svg)
```@raw html
<figcaption>
```
**Figure 1:** Example showing the angular separation...
```@raw html
</figcaption>
</figure>
```

but it'd be really convenient if this could instead be written something like

```@figure [sphere angles](sphereangles.svg)
**Figure 1:** Example showing the angular separation...
```

(of course up for debate on exact syntax).

I can volunteer to do a lot of the implementation work if someone wants to point me at how/where this could be inserted into Documenter. (i.e. Is it possible to just add a new expander type which is translated directly to something like the mixture of raw HTML/LaTeX and markdown like I'm currently doing manually, and then the expansions run recursively to actually build the document?)

This is also tangentially related to #433 since a custom expander could provide the LaTeX floating figure option to contrast an inline figure using normal Markdown image syntax.

[odow]

Doesn't the caption just use the alt-text?

![Example showing the angular separation...](sphereangles.svg)

[jmert]

No, it's not the same since you can't use arbitrary Markdown and formatted paragraph text within the alt-text. The use of <figure>+<figcaption> (or figure environment with \caption{...} in LaTeX) also have important semantic meanings — i.e. accessibility interpretations in HTML and rendering as a floating element in LaTeX, respectively.

The actual use case I have in mind is the following screenshot from some package documentation. (For context, the preceding paragraph is shown at the top with the figure and figure caption the rest of the image.)

---

[mortenpi]

Rather than implementing this as a new, special block in Documenter, I am thinking it would be better to make it easier for the user to implement their own custom blocks. Generally, for the HTML output, Documenter just needs something that would produce the necessary DOM Nodes. What we would need is an API to hook some custom user code in make.jl into Documenter.