Support complex figures. [API change]

Thanks and credit go to Aner Lucero, who laid the groundwork for this
feature in the 2021 GSoC project. He contributed many changes, including
modifications to the readers for HTML, JATS, and LaTeX, and to the HTML
and JATS writers.

Shared (Albert Krewinkel):

- The new function `figureDiv`, exported from `Text.Pandoc.Shared`,
  offers a standardized way to convert a figure into a Div element.

Readers (Aner Lucero):

- HTML reader: `<figure>` elements are parsed as figures, with the
  caption taken from the respective `<figcaption>` elements.

- JATS reader: The `<fig>` and `<caption>` elements are parsed into
  figure elements, even if the contents is more complex.

- LaTeX reader: support for figures with non-image contents and for
  subfigures.

- Markdown reader: paragraphs containing just an image are treated as
  figures if the `implicit_figures` extension is enabled. The identifier
  is used as the figure's identifier and the image description is also
  used as figure caption; all other attributes are treated as belonging
  to the image.

Writers (Aner Lucero, Albert Krewinkel):

- DokuWiki, Haddock, Jira, Man, MediaWiki, Ms, Muse, PPTX, RTF, TEI,
  ZimWiki writers: Figures are rendered like Div elements.

- Asciidoc writer: The figure contents is unwrapped; each image in the
  the figure becomes a separate figure.

- Classic custom writers: Figures are passed to the global function
  `Figure(caption, contents, attr)`, where `caption` and `contents` are
  strings and `attr` is a table of key-value pairs.

- ConTeXt writer: Figures are wrapped in a "placefigure" environment
  with `\startplacefigure`/`\endplacefigure`, adding the features
  caption and listing title as properties. Subfigures are place in a
  single row with the `\startfloatcombination` environment.

- DocBook writer: Uses `mediaobject` elements, unless the figure contains
  subfigures or tables, in which case the figure content is unwrapped.

- Docx writer: figures with multiple content blocks are rendered as
  tables with style `FigureTable`; like before, single-image figures are
  still output as paragraphs with style `Figure` or `Captioned Figure`,
  depending on whether a caption is attached.

- DokuWiki writer: Caption and "alt-text" are no longer combined. The
  alt text of a figure will now be lost in the conversion.

- FB2 writer: The figure caption is added as alt text to the images in
  the figure; pre-existing alt texts are kept.

- ICML writer: Only single-image figures are supported. The contents of
  figures with additional elements gets unwrapped.

- HTML writer: the alt text is no longer constructed from the caption,
  as was the case with implicit figures. This reduces duplication, but
  comes at the risk of images that are missing alt texts. Authors should
  take care to provide alt texts for all images.

  Some readers, most notably the Markdown reader with the
  `implicit_figures` extension, add a caption that's identical to the
  image description. The writer checks for this and adds an
  `aria-hidden` attribute to the `<figcaption>` element in that case.

- JATS writer: The `<fig>` and `<caption>` elements are used write
  figures.

- LaTeX writer: complex figures, e.g. with non-image contents and
  subfigures, are supported. The `subfigure` template variable is set if
  the document contains subfigures, triggering the conditional loading
  of the *subcaption* package. Contants of figures that contain tables
  are become unwrapped, as longtable environments are not allowed within
  figures.

- Markdown writer: figures are output as implicit figures if possible,
  via HTML if the `raw_html` extension is enabled, and as Div elements
  otherwise.

- OpenDocument writer: A separate paragraph is generated for each block
  element in a figure, each with style `FigureWithCaption`. Behavior for
  single-image figures therefore remains unchanged.

- Org writer: Only the first element in a figure is given a caption;
  additional block elements in the figure are appended without any
  caption being added.

- RST writer: Single-image figures are supported as before; the contents
  of more complex images become nested in a container of type `float`.

- Texinfo writer: Figures are rendered as float with type `figure`.

- Textile writer: Figures are rendered with the help of HTML elements.

- XWiki: Figures are placed in a group.

Co-authored-by: Aner Lucero <[email protected]>

28 files changed, 686 insertions, 129 deletions

diff --git a/test/command/2118.md b/test/command/2118.md
index 8be5c4886..63611c8cb 100644
--- a/test/command/2118.md
+++ b/test/command/2118.md
@@ -7,11 +7,16 @@
   \label{fig:setminus}
 \end{figure}
 ^D
-[ Para
-    [ Image
-        ( "fig:setminus" , [] , [ ( "width" , "80%" ) ] )
-        [ Str "Set" , Space , Str "subtraction" ]
-        ( "setminus.png" , "fig:" )
+[ Figure
+    ( "fig:setminus" , [] , [] )
+    (Caption
+       Nothing [ Plain [ Str "Set" , Space , Str "subtraction" ] ])
+    [ Plain
+        [ Image
+            ( "" , [] , [ ( "width" , "80%" ) ] )
+            []
+            ( "setminus.png" , "" )
+        ]
     ]
 ]
 ```
diff --git a/test/command/3577.md b/test/command/3577.md
index 2caeb7c11..3c42c3490 100644
--- a/test/command/3577.md
+++ b/test/command/3577.md
@@ -16,12 +16,15 @@
 \end{figure}
 ^D
 <figure>
-<img src="img1.jpg" alt="Caption 1" />
-<figcaption aria-hidden="true">Caption 1</figcaption>
+<figure>
+<img src="img1.jpg" />
+<figcaption>Caption 1</figcaption>
 </figure>
 <figure>
-<img src="img2.jpg" alt="Caption 2" />
-<figcaption aria-hidden="true">Caption 2</figcaption>
+<img src="img2.jpg" />
+<figcaption>Caption 2</figcaption>
+</figure>
+<figcaption>Subfigure with Subfloat</figcaption>
 </figure>
 ```
 ```
@@ -32,7 +35,7 @@
 \end{figure}
 ^D
 <figure>
-<img src="img1.jpg" alt="Caption 3" />
-<figcaption aria-hidden="true">Caption 3</figcaption>
+<img src="img1.jpg" />
+<figcaption>Caption 3</figcaption>
 </figure>
 ```
diff --git a/test/command/4183.md b/test/command/4183.md
index 8d6c65a01..e844f6a4d 100644
--- a/test/command/4183.md
+++ b/test/command/4183.md
@@ -4,7 +4,13 @@
   <img src="foo" alt="bar">
 </figure>
 ^D
-[ Para [ Image ( "" , [] , [] ) [] ( "foo" , "fig:" ) ] ]
+[ Figure
+    ( "" , [] , [] )
+    (Caption Nothing [])
+    [ Plain
+        [ Image ( "" , [] , [] ) [ Str "bar" ] ( "foo" , "" ) ]
+    ]
+]
 ```
 
 ```
@@ -18,8 +24,13 @@
   </figcaption>
 </figure>
 ^D
-[ Para
-    [ Image ( "" , [] , [] ) [ Str "baz" ] ( "foo" , "fig:" ) ]
+[ Figure
+    ( "" , [] , [] )
+    (Caption
+       Nothing [ Div ( "" , [] , [] ) [ Plain [ Str "baz" ] ] ])
+    [ Plain
+        [ Image ( "" , [] , [] ) [ Str "bar" ] ( "foo" , "" ) ]
+    ]
 ]
 ```
 
@@ -30,9 +41,9 @@
   <figcaption><p><em>baz</em></p></figcaption>
 </figure>
 ^D
-[ Para
-    [ Image
-        ( "" , [] , [] ) [ Emph [ Str "baz" ] ] ( "foo" , "fig:" )
-    ]
+[ Figure
+    ( "" , [] , [] )
+    (Caption Nothing [ Para [ Emph [ Str "baz" ] ] ])
+    [ Plain [ Image ( "" , [] , [] ) [] ( "foo" , "" ) ] ]
 ]
 ```
diff --git a/test/command/4420.md b/test/command/4420.md
index 36d697234..9d809a106 100644
--- a/test/command/4420.md
+++ b/test/command/4420.md
@@ -2,10 +2,8 @@
 % pandoc -f native -t rst
 [Para [Image ("",["align-right"],[("width","100px")]) [Str "image"] ("foo.png","fig:test")]]
 ^D
-.. figure:: foo.png
-   :alt: test
+.. image:: foo.png
+   :alt: image
    :align: right
    :width: 100px
-
-   image
 ```
diff --git a/test/command/4677.md b/test/command/4677.md
index 64c436005..15c8fd5ee 100644
--- a/test/command/4677.md
+++ b/test/command/4677.md
@@ -2,8 +2,8 @@
 % pandoc --to "markdown-bracketed_spans-fenced_divs-link_attributes-simple_tables-multiline_tables-grid_tables-pipe_tables-fenced_code_attributes-markdown_in_html_blocks-table_captions-smart"
 ![Caption](img.png){#img:1}
 ^D
-<figure>
-<img src="img.png" id="img:1" alt="Caption" />
+<figure id="img:1">
+<img src="img.png" alt="Caption" />
 <figcaption aria-hidden="true">Caption</figcaption>
 </figure>
 ```
diff --git a/test/command/5321.md b/test/command/5321.md
index 975852482..43e0ddc74 100644
--- a/test/command/5321.md
+++ b/test/command/5321.md
@@ -7,9 +7,14 @@
   <graphic xlink:href="foo.png" xlink:alt-text="baz" />
 </fig>
 ^D
-[ Para
-    [ Image
-        ( "fig-1" , [] , [] ) [ Str "bar" ] ( "foo.png" , "fig:" )
+[ Figure
+    ( "fig-1" , [] , [] )
+    (Caption Nothing [ Plain [ Str "bar" ] ])
+    [ Div
+        ( "" , [ "caption" ] , [] )
+        [ Header 6 ( "" , [] , [] ) [] , Para [ Str "bar" ] ]
+    , Para
+        [ Image ( "" , [] , [] ) [ Str "baz" ] ( "foo.png" , "" ) ]
     ]
 ]
 ```
@@ -24,11 +29,17 @@
   <graphic xlink:href="foo.png" xlink:alt-text="baz" />
 </fig>
 ^D
-[ Para
-    [ Image
-        ( "fig-1" , [] , [] )
-        [ Str "foo" , LineBreak , Str "bar" ]
-        ( "foo.png" , "fig:" )
+[ Figure
+    ( "fig-1" , [] , [] )
+    (Caption
+       Nothing [ Plain [ Str "foo" , LineBreak , Str "bar" ] ])
+    [ Div
+        ( "" , [ "caption" ] , [] )
+        [ Header 6 ( "" , [] , [] ) [ Str "foo" ]
+        , Para [ Str "bar" ]
+        ]
+    , Para
+        [ Image ( "" , [] , [] ) [ Str "baz" ] ( "foo.png" , "" ) ]
     ]
 ]
 ```
diff --git a/test/command/5368.md b/test/command/5368.md
index e8b54bf7b..9e09cee6a 100644
--- a/test/command/5368.md
+++ b/test/command/5368.md
@@ -15,21 +15,32 @@ Quux.
 [ OrderedList
     ( 1 , Decimal , Period )
     [ [ Para [ Str "foo" ]
-      , Para
-          [ Image
-              ( "" , [] , [] ) [ Str "bar" ] ( "bar.png" , "fig:" )
+      , Figure
+          ( "" , [] , [] )
+          (Caption Nothing [ Plain [ Str "bar" ] ])
+          [ Plain
+              [ Image ( "" , [] , [] ) [ Str "bar" ] ( "bar.png" , "" )
+              ]
           ]
       ]
     , [ Para [ Str "foo2" ]
-      , Para
-          [ Image
-              ( "" , [] , [] ) [ Str "bar2" ] ( "bar2.png" , "fig:" )
+      , Figure
+          ( "" , [] , [] )
+          (Caption Nothing [ Plain [ Str "bar2" ] ])
+          [ Plain
+              [ Image
+                  ( "" , [] , [] ) [ Str "bar2" ] ( "bar2.png" , "" )
+              ]
           ]
       ]
     , [ Para [ Str "foo3" ]
-      , Para
-          [ Image
-              ( "" , [] , [] ) [ Str "foo3" ] ( "foo3.png" , "fig:" )
+      , Figure
+          ( "" , [] , [] )
+          (Caption Nothing [ Plain [ Str "foo3" ] ])
+          [ Plain
+              [ Image
+                  ( "" , [] , [] ) [ Str "foo3" ] ( "foo3.png" , "" )
+              ]
           ]
       ]
     ]
diff --git a/test/command/5619.md b/test/command/5619.md
index 0f612ea67..7eec80cfd 100644
--- a/test/command/5619.md
+++ b/test/command/5619.md
@@ -6,32 +6,40 @@
 
   The caption. Here's what piggybacking on caption would look like {#fig:1}
 ^D
-[ Para
-    [ Image
-        ( "test" , [] , [ ( "width" , "1in" ) ] )
-        [ Str "The"
-        , Space
-        , Str "caption."
-        , Space
-        , Str "Here's"
-        , Space
-        , Str "what"
-        , Space
-        , Str "piggybacking"
-        , Space
-        , Str "on"
-        , Space
-        , Str "caption"
-        , Space
-        , Str "would"
-        , Space
-        , Str "look"
-        , Space
-        , Str "like"
-        , Space
-        , Str "{#fig:1}"
+[ Figure
+    ( "" , [] , [] )
+    (Caption
+       Nothing
+       [ Plain
+           [ Str "The"
+           , Space
+           , Str "caption."
+           , Space
+           , Str "Here's"
+           , Space
+           , Str "what"
+           , Space
+           , Str "piggybacking"
+           , Space
+           , Str "on"
+           , Space
+           , Str "caption"
+           , Space
+           , Str "would"
+           , Space
+           , Str "look"
+           , Space
+           , Str "like"
+           , Space
+           , Str "{#fig:1}"
+           ]
+       ])
+    [ Plain
+        [ Image
+            ( "test" , [] , [ ( "width" , "1in" ) ] )
+            [ Str "img1.jpg" ]
+            ( "img1.jpg" , "" )
         ]
-        ( "img1.jpg" , "fig:" )
     ]
 ]
 ```
diff --git a/test/command/6137.md b/test/command/6137.md
index a58b4876f..077044e07 100644
--- a/test/command/6137.md
+++ b/test/command/6137.md
@@ -134,24 +134,32 @@ This reference to Figure \ref{fig:label} works fine.
     , Space
     , Str "fine."
     ]
-, Para
-    [ Image
-        ( "fig:label" , [] , [ ( "width" , "\\textwidth" ) ] )
-        [ Str "A"
-        , Space
-        , Str "numbered"
-        , Space
-        , Str "caption,"
-        , Space
-        , Str "if"
-        , Space
-        , Str "I"
-        , Space
-        , Str "use"
-        , Space
-        , Str "pandoc-crossref."
+, Figure
+    ( "fig:label" , [] , [] )
+    (Caption
+       Nothing
+       [ Plain
+           [ Str "A"
+           , Space
+           , Str "numbered"
+           , Space
+           , Str "caption,"
+           , Space
+           , Str "if"
+           , Space
+           , Str "I"
+           , Space
+           , Str "use"
+           , Space
+           , Str "pandoc-crossref."
+           ]
+       ])
+    [ Plain
+        [ Image
+            ( "" , [] , [ ( "width" , "\\textwidth" ) ] )
+            []
+            ( "example.png" , "" )
         ]
-        ( "example.png" , "fig:" )
     ]
 ]
 ```
diff --git a/test/command/6774.md b/test/command/6774.md
index 66549c0f2..7e8db5b50 100644
--- a/test/command/6774.md
+++ b/test/command/6774.md
@@ -13,7 +13,7 @@ Chapter</text:span></text:a></text:p>
 % pandoc -f native -t opendocument+xrefs_name --quiet
 [Header 1 ("chapter1",[],[]) [Str "The",Space,Str "Chapter"]
 ,Para [Str "Chapter",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "The",Space,Str "Chapter"] ("#chapter1","")]
-,Para [Image ("lalune",[],[]) [Str "lalune"] ("lalune.jpg","fig:Voyage dans la Lune")]
+,Figure ("lalune",[],[]) (Caption Nothing [Para [Str "Voyage dans la Lune"]]) [Plain [Image ("",[],[]) [Str "lalune"] ("lalune.jpg","")]]
 ,Para [Str "Image",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "La",Space,Str "Lune"] ("#lalune","")]]
 ^D
 <text:h text:style-name="Heading_20_1" text:outline-level="1"><text:bookmark-start text:name="chapter1" />The
@@ -22,7 +22,7 @@ Chapter<text:bookmark-end text:name="chapter1" /></text:h>
 <text:bookmark-ref text:reference-format="text" text:ref-name="chapter1">The
 Chapter</text:bookmark-ref></text:p>
 <text:p text:style-name="FigureWithCaption"><draw:frame draw:name="img1"><draw:image xlink:href="lalune.jpg" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" /></draw:frame></text:p>
-<text:p text:style-name="FigureCaption">lalune</text:p>
+<text:p text:style-name="FigureCaption">Voyage dans la Lune</text:p>
 <text:p text:style-name="Text_20_body">Image 1 references
 <text:sequence-ref text:reference-format="caption" text:ref-name="lalune">La
 Lune</text:sequence-ref></text:p>
@@ -31,7 +31,7 @@ Lune</text:sequence-ref></text:p>
 % pandoc -f native -t opendocument+xrefs_number --quiet
 [Header 1 ("chapter1",[],[]) [Str "The",Space,Str "Chapter"]
 ,Para [Str "Chapter",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "The",Space,Str "Chapter"] ("#chapter1","")]
-,Para [Image ("lalune",[],[]) [Str "lalune"] ("lalune.jpg","fig:Voyage dans la Lune")]
+,Figure ("lalune",[],[]) (Caption Nothing [Para [Str "lalune"]]) [Plain [Image ("",[],[]) [Str "lalune"] ("lalune.jpg","Voyage dans la Lune")]]
 ,Para [Str "Image",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "La",Space,Str "Lune"] ("#lalune","")]]
 ^D
 <text:h text:style-name="Heading_20_1" text:outline-level="1"><text:bookmark-start text:name="chapter1" />The
@@ -47,7 +47,7 @@ Chapter<text:bookmark-end text:name="chapter1" /></text:h>
 % pandoc -f native -t opendocument+xrefs_number+xrefs_name --quiet
 [Header 1 ("chapter1",[],[]) [Str "The",Space,Str "Chapter"]
 ,Para [Str "Chapter",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "The",Space,Str "Chapter"] ("#chapter1","")]
-,Para [Image ("lalune",[],[]) [Str "lalune"] ("lalune.jpg","fig:Voyage dans la Lune")]
+,Figure ("lalune",[],[]) (Caption Nothing [Para [Str "Voyage dans la Lune"]]) [Plain [Image ("",[],[]) [Str "lalune"] ("lalune.jpg","")]]
 ,Para [Str "Image",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "La",Space,Str "Lune"] ("#lalune","")]]
 ^D
 <text:h text:style-name="Heading_20_1" text:outline-level="1"><text:bookmark-start text:name="chapter1" />The
@@ -56,7 +56,7 @@ Chapter<text:bookmark-end text:name="chapter1" /></text:h>
 <text:bookmark-ref text:reference-format="number" text:ref-name="chapter1"></text:bookmark-ref><text:s /><text:bookmark-ref text:reference-format="text" text:ref-name="chapter1">The
 Chapter</text:bookmark-ref></text:p>
 <text:p text:style-name="FigureWithCaption"><draw:frame draw:name="img1"><draw:image xlink:href="lalune.jpg" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" /></draw:frame></text:p>
-<text:p text:style-name="FigureCaption">lalune</text:p>
+<text:p text:style-name="FigureCaption">Voyage dans la Lune</text:p>
 <text:p text:style-name="Text_20_body">Image 1 references
 <text:sequence-ref text:reference-format="value" text:ref-name="lalune"></text:sequence-ref><text:s /><text:sequence-ref text:reference-format="caption" text:ref-name="lalune">La
 Lune</text:sequence-ref></text:p>
diff --git a/test/command/figures-context.md b/test/command/figures-context.md
new file mode 100644
index 000000000..1f93d63ff
--- /dev/null
+++ b/test/command/figures-context.md
@@ -0,0 +1,48 @@
+# Figure with one image, caption and label
+
+```
+% pandoc -t context -f html
+<figure>
+  <img src="mandrill.jpg" />
+  <figcaption><q>The Mandrill</q>, a photo used in
+    image processing tests.</figcaption>
+</figure>
+^D
+\startplacefigure[title={\quotation{The Mandrill}, a photo used in image
+processing tests.}]
+{\externalfigure[mandrill.jpg]}
+\stopplacefigure
+```
+
+# Nested figures
+
+```
+% pandoc -t context -f html
+<figure id="test-images">
+  <figure id="mandrill">
+    <img src="../testing/mandrill.jpg">
+    <figcaption><q>The Mandrill</q> is a commonly used test image.</figcaption>
+  </figure>
+  <figure id="peppers">
+    <img src="../testing/peppers.webp" >
+    <figcaption>Another test image. This one is called <q>peppers</q>.</figcaption>
+  </figure>
+  <figcaption>Signal processing test images.</figcaption>
+</figure>
+^D
+\startplacefigure[reference=test-images,title={Signal processing test
+images.}]
+\startfloatcombination
+\startplacefigure[reference=mandrill,title={\quotation{The Mandrill} is
+a commonly used test image.}]
+{\externalfigure[../testing/mandrill.jpg]}
+\stopplacefigure
+
+\startplacefigure[reference=peppers,title={Another test image. This one
+is called \quotation{peppers}.}]
+{\externalfigure[../testing/peppers.webp]}
+\stopplacefigure
+
+\stopfloatcombination
+\stopplacefigure
+```
diff --git a/test/command/figures-fb2.md b/test/command/figures-fb2.md
new file mode 100644
index 000000000..63aa86dc9
--- /dev/null
+++ b/test/command/figures-fb2.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f native -t fb2
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+<?xml version="1.0" encoding="UTF-8"?>
+<FictionBook xmlns="http://www.gribuser.ru/xml/fictionbook/2.0" xmlns:l="http://www.w3.org/1999/xlink"><description><title-info><genre>unrecognised</genre></title-info><document-info><program-used>pandoc</program-used></document-info></description><body><title><p /></title><section><p>content</p></section></body></FictionBook>
+```
diff --git a/test/command/figures-haddock.md b/test/command/figures-haddock.md
new file mode 100644
index 000000000..9a63861d7
--- /dev/null
+++ b/test/command/figures-haddock.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f native -t haddock
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+content
+```
diff --git a/test/command/figures-html.md b/test/command/figures-html.md
new file mode 100644
index 000000000..3718246d1
--- /dev/null
+++ b/test/command/figures-html.md
@@ -0,0 +1,92 @@
+# Writer
+
+HTML5 figure with caption and content.
+
+```
+% pandoc -f native -t html5
+[Figure ("fig-id",[],[]) (Caption Nothing [Plain [Str "caption"]]) [Para [Str "content"]]]
+
+^D
+<figure id="fig-id">
+<p>content</p>
+<figcaption>caption</figcaption>
+</figure>
+```
+
+HTML5 figure with NO caption and content.
+
+```
+% pandoc -f native -t html5
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+<figure id="fig-id">
+<p>content</p>
+</figure>
+```
+
+HTML4 figure with caption and content.
+
+```
+% pandoc -f native -t html4
+[Figure ("fig-id",[],[]) (Caption Nothing [Plain [Str "caption"]]) [Para [Str "content"]]]
+
+^D
+<div class="float" id="fig-id">
+<p>content</p>
+<div class="figcaption">caption</div>
+</div>
+```
+
+HTML4 figure with NO caption and content.
+
+```
+% pandoc -f native -t html4
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+<div class="float" id="fig-id">
+<p>content</p>
+</div>
+```
+
+# Reader
+
+Figure with caption and multiple elements.
+
+```
+% pandoc -f html -t native
+<figure class="important">
+  <img src="../media/rId25.jpg" />
+  <ul> <li> ITEM </li> </ul>
+  <figcaption> CAP2 </figcaption>
+</figure>
+^D
+[ Figure
+    ( "" , [ "important" ] , [] )
+    (Caption Nothing [ Plain [ Str "CAP2" ] ])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "../media/rId25.jpg" , "" ) ]
+    , BulletList [ [ Plain [ Str "ITEM" ] ] ]
+    ]
+]
+```
+
+Figure without caption.
+
+```
+% pandoc -f html -t native
+<figure class="important">
+  <img src="../media/rId25.jpg" />
+  <ul> <li> ITEM </li> </ul>
+</figure>
+^D
+[ Figure
+    ( "" , [ "important" ] , [] )
+    (Caption Nothing [])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "../media/rId25.jpg" , "" ) ]
+    , BulletList [ [ Plain [ Str "ITEM" ] ] ]
+    ]
+]
+```
diff --git a/test/command/figures-jats.md b/test/command/figures-jats.md
new file mode 100644
index 000000000..a5089df2a
--- /dev/null
+++ b/test/command/figures-jats.md
@@ -0,0 +1,14 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t jats
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Str "Text"],
+Para [Image ("fig-id-2",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+<fig id="fig-id">
+  <caption><p>Caption</p></caption>
+  <p>Text</p>
+  <graphic id="fig-id-2" mimetype="image" mime-subtype="png" xlink:href="foo.png" xlink:title="fig:" />
+</fig>
+```
diff --git a/test/command/figures-jira.md b/test/command/figures-jira.md
new file mode 100644
index 000000000..7517b7e0b
--- /dev/null
+++ b/test/command/figures-jira.md
@@ -0,0 +1,9 @@
+A figure with title
+```
+% pandoc -f native -t jira
+[Figure ("fig-id",[],[("title","This is the title")]) (Caption Nothing []) []]
+^D
+{panel:title=This is the title}
+{anchor:fig-id}
+{panel}
+```
diff --git a/test/command/figures-latex.md b/test/command/figures-latex.md
new file mode 100644
index 000000000..cebce971e
--- /dev/null
+++ b/test/command/figures-latex.md
@@ -0,0 +1,83 @@
+# Figure with one image, caption and label
+
+```
+% pandoc -f latex -t native
+\begin{document}
+  \begin{figure}
+    \includegraphics{../../media/rId25.jpg}
+    \caption{CAP}
+    \label{LAB}
+  \end{figure}
+\end{document}
+^D
+[ Figure
+    ( "LAB" , [] , [] )
+    (Caption Nothing [ Plain [ Str "CAP" ] ])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "../../media/rId25.jpg" , "" )
+        ]
+    ]
+]
+```
+
+# Nested figures
+
+```
+% pandoc -f latex -t native
+\begin{figure}
+  \begin{subfigure}[b]{0.5\textwidth}
+    \begin{subfigure}[b]{0.5\textwidth}
+      \centering
+      \includegraphics{test/media/rId25.jpg}
+      \caption{CAP1.1}
+    \end{subfigure}
+    \begin{subfigure}[b]{0.5\textwidth}
+      \centering
+      \includegraphics{test/media/rId25.jpg}
+      \caption{CAP1.2}
+    \end{subfigure}
+    \caption{CAP1}
+    \label{fig:inner1}
+  \end{subfigure}
+  \begin{subfigure}[b]{0.5\textwidth}
+    \includegraphics{test/media/rId25.jpg}
+    \caption{CAP2}
+    \label{fig:inner2}
+  \end{subfigure}
+  \caption{CAP}
+  \label{fig:outer}
+\end{figure}
+^D
+[ Figure
+    ( "fig:outer" , [] , [] )
+    (Caption Nothing [ Plain [ Str "CAP" ] ])
+    [ Figure
+        ( "fig:inner1" , [] , [] )
+        (Caption Nothing [ Plain [ Str "CAP1" ] ])
+        [ Figure
+            ( "" , [] , [] )
+            (Caption Nothing [ Plain [ Str "CAP1.1" ] ])
+            [ Plain
+                [ Image
+                    ( "" , [] , [] ) [] ( "test/media/rId25.jpg" , "" )
+                ]
+            ]
+        , Figure
+            ( "" , [] , [] )
+            (Caption Nothing [ Plain [ Str "CAP1.2" ] ])
+            [ Plain
+                [ Image
+                    ( "" , [] , [] ) [] ( "test/media/rId25.jpg" , "" )
+                ]
+            ]
+        ]
+    , Figure
+        ( "fig:inner2" , [] , [] )
+        (Caption Nothing [ Plain [ Str "CAP2" ] ])
+        [ Plain
+            [ Image ( "" , [] , [] ) [] ( "test/media/rId25.jpg" , "" )
+            ]
+        ]
+    ]
+]
+```
diff --git a/test/command/figures-markdown.md b/test/command/figures-markdown.md
new file mode 100644
index 000000000..4d3ea4185
--- /dev/null
+++ b/test/command/figures-markdown.md
@@ -0,0 +1,12 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t markdown
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+<figure id="fig-id">
+<p><img src="foo.png" title="fig:" /></p>
+<figcaption><p>Caption</p></figcaption>
+</figure>
+```
diff --git a/test/command/figures-mediawiki.md b/test/command/figures-mediawiki.md
new file mode 100644
index 000000000..63bb2a96d
--- /dev/null
+++ b/test/command/figures-mediawiki.md
@@ -0,0 +1,14 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t mediawiki
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+<div id="fig-id" class="figure">
+
+[[File:foo.png|thumb|none]]
+
+
+</div>
+```
diff --git a/test/command/figures-org.md b/test/command/figures-org.md
new file mode 100644
index 000000000..bfa5c6de1
--- /dev/null
+++ b/test/command/figures-org.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f native -t org
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+<<fig-id>>
+content
+```
+
+```
+% pandoc -f native -t org
+[Figure ("",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+content
+```
diff --git a/test/command/figures-rst.md b/test/command/figures-rst.md
new file mode 100644
index 000000000..fac1145ad
--- /dev/null
+++ b/test/command/figures-rst.md
@@ -0,0 +1,10 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t rst
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+.. figure:: foo.png
+   :alt: fig:
+```
diff --git a/test/command/figures-texinfo.md b/test/command/figures-texinfo.md
new file mode 100644
index 000000000..f50c6b5bb
--- /dev/null
+++ b/test/command/figures-texinfo.md
@@ -0,0 +1,115 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t texinfo
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+@node Top
+@top Top
+
+@float Figure
+@image{foo,,,,png}
+@caption{Caption}
+@end float
+```
+
+Float that has no caption and doesn't contain a `SimpleFigure`
+
+```
+% pandoc -f native -t texinfo
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Image ("",[],[]) [] ("foo.png", "")]]]
+
+^D
+@node Top
+@top Top
+
+@float
+@image{foo,,,,png}
+@end float
+```
+
+Table float with caption at the figure level.
+
+```
+% pandoc -f native -t texinfo
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]])
+[Table ("",[],[]) (Caption Nothing
+ [])
+ [(AlignDefault,ColWidthDefault)
+ ,(AlignDefault,ColWidthDefault)
+ ,(AlignDefault,ColWidthDefault)]
+ (TableHead ("",[],[])
+ [Row ("",[],[])
+  [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+   [Plain [Str "Fruit"]]
+  ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+   [Plain [Str "Price"]]
+  ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+   [Plain [Str "Quantity"]]]])
+ [(TableBody ("",[],[]) (RowHeadColumns 0)
+  []
+  [Row ("",[],[])
+   [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+    [Plain [Str "Apple"]]
+   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+    [Plain [Str "25",Space,Str "cents"]]
+   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+    [Plain [Str "33"]]]
+  ,Row ("",[],[])
+   [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+    [Plain [Str "\"Navel\"",Space,Str "Orange"]]
+   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+    [Plain [Str "35",Space,Str "cents"]]
+   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+    [Plain [Str "22"]]]
+  ,Row ("",[],[])
+   [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+    []
+   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+    []
+   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+    [Plain [Str "45"]]]])]
+ (TableFoot ("",[],[])
+ [])]]
+
+^D
+@node Top
+@top Top
+
+@float Table
+@multitable {"Navel" Orange} {35 cents} {Quantity} 
+@headitem 
+Fruit
+ @tab Price
+ @tab Quantity
+@item 
+Apple
+ @tab 25 cents
+ @tab 33
+@item 
+"Navel" Orange
+ @tab 35 cents
+ @tab 22
+@item 
+45
+@end multitable
+@caption{Caption}
+@end float
+```
+
+Float the isn't a table nor a figure.
+
+```
+% pandoc -f native -t texinfo
+[Figure ("fig-id",[],[]) (Caption Nothing [Para[ Str "Caption"]]) [Para [Str "Content"]]]
+
+^D
+@node Top
+@top Top
+
+@float
+Content
+@caption{Caption}
+@end float
+```
diff --git a/test/command/figures-textile.md b/test/command/figures-textile.md
new file mode 100644
index 000000000..27c60cbe8
--- /dev/null
+++ b/test/command/figures-textile.md
@@ -0,0 +1,31 @@
+```
+% pandoc -f native -t textile
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "")]]]
+
+^D
+<figure id="fig-id">
+
+<figcaption>
+
+Caption
+
+</figcaption>
+
+!foo.png!
+
+
+</figure>
+```
+
+```
+% pandoc -f native -t textile
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Image ("",[],[]) [] ("foo.png", "")]]]
+
+^D
+<figure id="fig-id">
+
+!foo.png!
+
+
+</figure>
+```
diff --git a/test/command/figures-xwiki.md b/test/command/figures-xwiki.md
new file mode 100644
index 000000000..0b4e84dc6
--- /dev/null
+++ b/test/command/figures-xwiki.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f native -t xwiki
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+(((
+{{id name="fig-id" /}}content
+
+)))
+```
diff --git a/test/command/figures-zimwiki.md b/test/command/figures-zimwiki.md
new file mode 100644
index 000000000..a2d4bcd9a
--- /dev/null
+++ b/test/command/figures-zimwiki.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f native -t zimwiki
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+content
+
+
+```
diff --git a/test/command/html-read-figure.md b/test/command/html-read-figure.md
index d7eb96bb4..9d7cc163a 100644
--- a/test/command/html-read-figure.md
+++ b/test/command/html-read-figure.md
@@ -5,9 +5,11 @@
   <figcaption>bar</figcaption>
 </figure>
 ^D
-[ Para
-    [ Image
-        ( "" , [] , [] ) [ Str "bar" ] ( "foo.png" , "fig:voyage" )
+[ Figure
+    ( "" , [] , [] )
+    (Caption Nothing [ Plain [ Str "bar" ] ])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "foo.png" , "voyage" ) ]
     ]
 ]
 ```
@@ -19,9 +21,11 @@
   <img src="foo.png" title="voyage">
 </figure>
 ^D
-[ Para
-    [ Image
-        ( "" , [] , [] ) [ Str "bar" ] ( "foo.png" , "fig:voyage" )
+[ Figure
+    ( "" , [] , [] )
+    (Caption Nothing [ Plain [ Str "bar" ] ])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "foo.png" , "voyage" ) ]
     ]
 ]
 ```
@@ -32,8 +36,12 @@
   <img src="foo.png" title="voyage">
 </figure>
 ^D
-[ Para
-    [ Image ( "" , [] , [] ) [] ( "foo.png" , "fig:voyage" ) ]
+[ Figure
+    ( "" , [] , [] )
+    (Caption Nothing [])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "foo.png" , "voyage" ) ]
+    ]
 ]
 ```
 
@@ -44,9 +52,11 @@
   <figcaption>bar</figcaption>
 </figure>
 ^D
-[ Para
-    [ Image
-        ( "" , [] , [] ) [ Str "bar" ] ( "foo.png" , "fig:voyage" )
+[ Figure
+    ( "" , [] , [] )
+    (Caption Nothing [ Plain [ Str "bar" ] ])
+    [ Para
+        [ Image ( "" , [] , [] ) [] ( "foo.png" , "voyage" ) ]
     ]
 ]
 ```
@@ -55,11 +65,17 @@
 % pandoc -f html -t native
 <figure><img src="foo.png" title="voyage" alt="this is ignored"><figcaption>bar <strong>baz</strong></figcaption></figure>
 ^D
-[ Para
-    [ Image
-        ( "" , [] , [] )
-        [ Str "bar" , Space , Strong [ Str "baz" ] ]
-        ( "foo.png" , "fig:voyage" )
+[ Figure
+    ( "" , [] , [] )
+    (Caption
+       Nothing
+       [ Plain [ Str "bar" , Space , Strong [ Str "baz" ] ] ])
+    [ Plain
+        [ Image
+            ( "" , [] , [] )
+            [ Str "this" , Space , Str "is" , Space , Str "ignored" ]
+            ( "foo.png" , "voyage" )
+        ]
     ]
 ]
 ```
diff --git a/test/command/jats-figure-alt-text.md b/test/command/jats-figure-alt-text.md
index 229e52eda..d1ff67087 100644
--- a/test/command/jats-figure-alt-text.md
+++ b/test/command/jats-figure-alt-text.md
@@ -8,11 +8,15 @@
   <graphic xlink:href="foo.png" xlink:alt-text="baz" />
 </fig>
 ^D
-[ Para
-    [ Image
-        ( "fig-1" , [] , [ ( "alt" , "alternative-decription" ) ] )
-        [ Str "bar" ]
-        ( "foo.png" , "fig:" )
+[ Figure
+    ( "fig-1" , [] , [] )
+    (Caption Nothing [ Plain [ Str "bar" ] ])
+    [ Div
+        ( "" , [ "caption" ] , [] )
+        [ Header 6 ( "" , [] , [] ) [] , Para [ Str "bar" ] ]
+    , Plain [ Str "alternative-decription" ]
+    , Para
+        [ Image ( "" , [] , [] ) [ Str "baz" ] ( "foo.png" , "" ) ]
     ]
 ]
 ```
diff --git a/test/command/refs.md b/test/command/refs.md
index c6457be4c..cf2395fb8 100644
--- a/test/command/refs.md
+++ b/test/command/refs.md
@@ -133,11 +133,12 @@ Accuracy~\eqref{eq:Accuracy} is the proportion, measuring true results among all
 
 Figure \ref{fig:Logo} illustrated the SVG logo
 ^D
-[ Para
-    [ Image
-        ( "fig:Logo" , [] , [] )
-        [ Str "Logo" ]
-        ( "command/SVG_logo.svg" , "fig:" )
+[ Figure
+    ( "fig:Logo" , [] , [] )
+    (Caption Nothing [ Plain [ Str "Logo" ] ])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "command/SVG_logo.svg" , "" )
+        ]
     ]
 , Para
     [ Str "Figure"
@@ -195,25 +196,28 @@ Figure \ref{fig:Logo2} illustrated the SVG logo
 Figure \ref{fig:Logo3} illustrated the SVG logo
 ^D
 [ Header 1 ( "one" , [] , [] ) [ Str "One" ]
-, Para
-    [ Image
-        ( "fig:Logo" , [] , [] )
-        [ Str "Logo" ]
-        ( "command/SVG_logo.svg" , "fig:" )
+, Figure
+    ( "fig:Logo" , [] , [] )
+    (Caption Nothing [ Plain [ Str "Logo" ] ])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "command/SVG_logo.svg" , "" )
+        ]
     ]
-, Para
-    [ Image
-        ( "fig:Logo2" , [] , [] )
-        [ Str "Logo2" ]
-        ( "command/SVG_logo2.svg" , "fig:" )
+, Figure
+    ( "fig:Logo2" , [] , [] )
+    (Caption Nothing [ Plain [ Str "Logo2" ] ])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "command/SVG_logo2.svg" , "" )
+        ]
     ]
 , Header 1 ( "two" , [] , [] ) [ Str "Two" ]
 , Header 2 ( "subone" , [] , [] ) [ Str "Subone" ]
-, Para
-    [ Image
-        ( "fig:Logo3" , [] , [] )
-        [ Str "Logo3" ]
-        ( "command/SVG_logo3.svg" , "fig:" )
+, Figure
+    ( "fig:Logo3" , [] , [] )
+    (Caption Nothing [ Plain [ Str "Logo3" ] ])
+    [ Plain
+        [ Image ( "" , [] , [] ) [] ( "command/SVG_logo3.svg" , "" )
+        ]
     ]
 , Para
     [ Str "Figure"