Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature request: custom expander for figures #1263

Open
jmert opened this issue Mar 19, 2020 · 3 comments
Open

Feature request: custom expander for figures #1263

jmert opened this issue Mar 19, 2020 · 3 comments
Labels
Status: Speculative It's unknown if this is something that we wan't to do Type: Feature

Comments

@jmert
Copy link
Contributor

jmert commented Mar 19, 2020

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
Copy link
Collaborator

odow commented Oct 20, 2021

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

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

@jmert
Copy link
Contributor Author

jmert commented Oct 24, 2021

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.)


image

@mortenpi mortenpi added Type: Feature Status: Speculative It's unknown if this is something that we wan't to do labels Mar 25, 2022
@mortenpi
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Status: Speculative It's unknown if this is something that we wan't to do Type: Feature
Projects
None yet
Development

No branches or pull requests

3 participants