Pandoc filter implementing a better logic for image-in-a-para vs. figure in Markdown

no-fig-pandoc.lua

--[===[# `no-fig-pandoc.lua`

Pandoc filter implementing a better logic for image-in-a-para vs. figure in Markdown

This Pandoc filter strips the Figure around an Image if the Figure
has no other practical child than that Image, by replacing the Figure
with a paragraph containing the Image and a non-breaking space (U+00A0)
    
An Image with a class `.fig` will cause the Figure to be preserved.
    
## Example

``````markdown
![Image](path/to/img.png)

![Figure](path/to/fig.png){.fig}
``````

``````sh
% pandoc -L no-fig.lua example.md
``````

``````html
<p><img src="path/to/img.png" alt="Image" /> </p>
<figure>
<img src="path/to/fig.png" class="fig" alt="Figure" />
<figcaption aria-hidden="true">Figure</figcaption>
</figure>
``````

## Gist

<https://gist.github.com/bpj/6664b0b0755e7ebe9007de4d1426d400>

## Author

Benct Philip Jonsson <[email protected]>

## Copyright and License

This software is Copyright (c) 2023 by Benct Philip Jonsson.

This is free software, licensed under:

  The MIT (X11) License

http://www.opensource.org/licenses/mit-license.php
]===]

--[[If the Figure has only one child which is a Plain or Para,
and that child has only one child which is an Image:
    
-   If the Image has a class .fig leave it as a Figure! 
-   Otherwise wrap the Image followed by
a Str with an nbspace = U+00A0 in a Para. 
]]

Figure = function(fig)
  if 1 == #fig.content then
    local child = fig.content[1]
    if 'Plain' == child.tag or 'Para' == child.tag then
      if 1 == #child.content and 'Image' == child.content[1].tag then
        local img = child.content[1]
        if img.classes:includes('fig') then
          return nil
        end
        return pandoc.Para({
          img,
          pandoc.Str("\u{a0}")
        })
      end
    end
  end
  return nil
end

no-fig-readme.md

no-fig.lua

Pandoc filter implementing a better logic for image-in-a-para vs. figure in Markdown

This Pandoc filter strips the Figure around an Image if the Figure has no other practical child than that Image, by replacing the Figure with a paragraph containing the Image and a non-breaking space (U+00A0)

An Image with a class .fig will cause the Figure to be preserved.

The magic non-breaking space.

The nbspace isn't strictly necessary but it helps if you convert to Markdown and want to avoid getting a figure in the future, because when Pandoc sees that the paragraph contains something besides the Image it will not wrap the Image in a Figure but leave the paragraph as is.

If you insert that nbspace manually into your Markdown you will not need this filter. Just type

Paragraph before.

![Image](path/to/img.png)\<space>

Paragraph after.

Where \<space> should be replaced with an actual backslash character (U+005C) followed by an actual space character (U+0020) before the line break.

If you actually want a Figure

This filter practically disables Pandoc's figure detection mechanism, but if the filter sees that an Image which it would otherwise unwrap from a Figure has a class .fig it will leave the Figure as-is.

Paragraph before.

![Figure](path/to/figure.png){.fig}

Paragraph after.

Thus this filter so to speak inverts Pandoc's usual logic for detecting figures in Markdown:

• If you do not want a figure you need not do anything special.

• If you do want a figure you have to add something — and a very visible and self-expanatory something!

Example

![Image](path/to/img.png)

![Figure](path/to/fig.png){.fig}

% pandoc -L no-fig.lua example.md

<p><img src="path/to/img.png" alt="Image" /> </p>
<figure>
<img src="path/to/fig.png" class="fig" alt="Figure" />
<figcaption aria-hidden="true">Figure</figcaption>
</figure>

Gist

https://gist.github.com/bpj/6664b0b0755e7ebe9007de4d1426d400

Author

Benct Philip Jonsson [email protected]

Copyright and License

This software is Copyright (c) 2023 by Benct Philip Jonsson.

This is free software, licensed under:

The MIT (X11) License

http://www.opensource.org/licenses/mit-license.php