Markdown figure input propossal and discussion.

[argent0]

Hi, I'm starting to work on the code for the markdown reader.

I'm tentatively aiming for this representation:

::: {#fig-id .figure}
![](foo.png)
:::: { .caption}
caption
::::
:::

That should produce:

[Figure ("fig-id",[],[]) (Caption Nothing [Plain [Str "caption"]]) [Para [Image ("",[],[]) [] ("foo.png","fig:")]]]

There is the issue that fenced divs are only parsed when Ext_fenced_divs is enabled.

Impementation

Explicit notation

As discussed below this was implemented using a Lua filter md-figure-explicit.lua:

--- Translate Divs with the "figure" class into Figure elements.
-- The contents of last child Div with the "caption" class will be used as the
-- figure caption.
function Div(div)

  local content = div.content
  local attr = div.attr
  local null_caption = {
    short = {},
    long = {}
  }

  if attr.classes:includes "figure" then

    local new_content =  pandoc.List({})

    -- A div with the caption class is captured as the figure's
    -- caption.
    for _,elem in pairs(div.content) do
      if elem.t == 'Div' then
        null_caption.long = elem.content
      else
        new_content:insert(elem)
      end
    end


    -- Remove the figure for `SimpleFigure` with no caption inside a Figure.
    local final_content = pandoc.List({})

    for _,elem in pairs(new_content) do
      -- Check that it is a simple figure with no caption
      if elem.t == 'Para' and 
        #elem.content == 1 and
        elem.content[1].t == 'Image' and
        #elem.content[1].caption == 0 then

        local image = elem.content[1]
        final_content:insert(pandoc.Plain({image}))
      else
        final_content:insert(elem)
      end
    end

    -- Remove the figure class in the output
    attr.classes = attr.classes:filter(
    function(c) return c ~= "figure" end)

    return pandoc.Figure(final_content, null_caption, attr)
  end

  -- Return an identical div when it lacks the "figure" class.
  return pandoc.Div(content, attr)
end

Example run:

Input

::: { .figure }

![](test/media/rId25.jpg "")

![](test/media/rId25.jpg "")

:::: {.caption}
caption
::::

:::

Output

$ pandoc -f markdown -t native --lua-filter=md-figure-explicit.lua fig-explicit.md
[Figure ("",[],[]) (Caption (Just []) [Para [Str "caption"]]) [Plain [Image ("",[],[]) [] ("test/media/rId25.jpg","")],Plain [Image ("",[],[]) [] ("test/media/rId25.jpg","")]]]

$ pandoc -f markdown -t html --lua-filter=md-figure-explicit.lua fig-explicit.md
<figure>
<img src="test/media/rId25.jpg" />
<img src="test/media/rId25.jpg" />
<figcaption><p>caption</p></figcaption>
</figure>

Implicit notation

--- Translate Divs with the "figure" class into Figure elements.
-- The contents of last paragraph became the figure caption will be used as the
-- figure caption.
function Div(div)

  local content = div.content
  local attr = div.attr
  local null_caption = {
    short = {},
    long = {}
  }

  if attr.classes:includes "figure" then

    local new_content =  pandoc.List({})

    -- Capture the last element
    local last_elem = nil

    for _,elem in pairs(div.content) do
      if last_elem then
        new_content:insert(last_elem)
      end
      last_elem = elem
    end

    -- If the last element is a paragraph, use it as caption.
    if last_elem then
      if last_elem.t == 'Para' then
        null_caption.long = { last_elem }
      else
        new_content:insert(last_elem)
      end
    end

    -- Remove the figure for `SimpleFigure` with no caption inside a Figure.
    local final_content = pandoc.List({})

    for _,elem in pairs(new_content) do
      -- Check that it is a simple figure with no caption
      if elem.t == 'Para' and 
        #elem.content == 1 and
        elem.content[1].t == 'Image' and
        #elem.content[1].caption == 0 then

        local image = elem.content[1]
        final_content:insert(pandoc.Plain({image}))
      else
        final_content:insert(elem)
      end
    end

    -- Remove the figure class in the output
    attr.classes = attr.classes:filter(
      function(c) return c ~= "figure" end)

    return pandoc.Figure(final_content, null_caption, attr)
  end

  -- Return an identical div when it lacks the "figure" class.
  return pandoc.Div(content, attr)
end

Input

::: { .figure }

one
two
three

![](test/media/rId25.jpg "")

![](test/media/rId25.jpg "")

caption

:::

Output

$ pandoc -f markdown -t native --lua-filter=md-figure-implicit.lua fig-implict.md
[Figure ("",[],[]) (Caption (Just []) [Para [Str "caption"]]) [Para [Str "one",SoftBreak,Str "two",SoftBreak,Str "three"],Plain [Image ("",[],[]) [] ("test/media/rId25.jpg","")],Plain [Image ("",[],[]) [] ("test/media/rId25.jpg","")]]]

$pandoc -f markdown -t html --lua-filter=md-figure-implicit.lua fig-implict.md
<figure>
<p>one two three</p>
<img src="test/media/rId25.jpg" />
<img src="test/media/rId25.jpg" />
<figcaption><p>caption</p></figcaption>
</figure>

Sample Firefox's HTML rendering

For the implicit syntax example.

[cderv]

There is the issue that fenced divs are only parsed when Ext_fenced_divs is enabled.

I don't see that as an issue but as a requirement. Same as you need +implicit_figures currently to get a captioned figure. Also I see this as a Pandoc's Markdown feature and fenced divs is activated by default in Pandoc's Markdown, so this seems adequat.

Regarding the representation, I wonder if we need to be this explicit (maybe it is a aim for Pandoc) or if we could be more implicit to be simpler. For example, something

::: {#fig-id}
![image caption](foo.png "Title of figure"){alt = "alt text}

Figure environment caption
:::

would be

• label id starting with fig- means figure environment
• Image inside can use the usual syntax
• Last paragraph of the fenced div will be used as the figure environment caption.

This is more implicit and I see how being more explicit can be good too

::: {#anyid .figure}
![image caption](foo.png "Title of figure"){alt = "alt text}
:::: {.caption}
Figure environment caption
::::
:::

I am just wondering: is there any use case where we could need to create a div of class figure in HTML5 for example ?

<div class = "figure>
content
</div>

because if

::: {.figure}

:::

creates what is described in #24 (comment)

<figure>

</figure>

There would be now more markdown syntax to generate the former.

Maybe it is be twisted but I am just sharing my thoughts 😅

Overall, I like the use of Fenced Divs for this !

[tarleb]

What do you two think about doing this as a filter instead of building it into the reader?

I'm unsure if jgm would accept this syntax for figures, because of the ambiguity mentioned by Christophe, and because Markdown is supposed to be language independent, so it should not require English keywords. (There are exceptions though, e.g. [this is typeset using small caps]{.smallcaps}; it's not a hard and fast rule.)

The proposed div-based structure should make this easy to accomplish now that we have Lua filter support for figures.

[tarleb]

The additional advantage of a filter would be that it would work with both pandoc Markdown and CommonMark.

[cderv]

because Markdown is supposed to be language independent, so it should not require English keywords

That is good to know ! I never realized that. And there are indeed exception:

# Header {.unnumbered .unlisted}

😉

What do you two think about doing this as a filter instead of building it into the reader?

Doing it as a Lua filter is a good idea. It could also be a way to try out a syntax for sometimes and get feedback before putting anything in.

now that we have Lua filter support for figures.

That is great !! 👏

[argent0]

Thanks for the comments I'll see to implement this with a filter using the explicit syntax and another with the implicit one.

The implicit one wouldn't allow for a figure without a caption and a paragraph at the end. But maybe that's also twisted.

[argent0]

As discussed, this was implemented as a Lua filter.

[argent0]

Now the SimpleFigure constructions with no caption are transformed to a plain image. I've also included some screenshots of the rendered html output.