Side-by-side images

[janosh]

Is there an example of how to use HTML or LaTeX subfigure for rendering two images side-by-side? Needs to work on Overleaf which uses Package: markdown 2022/05/31 v2.15.2 (unless there's a way to automatically update markdown on Overleaf?).

[Witiko]

Is there an example of how to use HTML or LaTeX subfigure for rendering two images side-by-side?

I don't think there is such an example. However, there are multiple ways in which you could do that. Some of them require no programming effort whatsoever but will lead to less readable markdown code stuffed with formatting commands:

1. Enable the hybrid option and just type LaTeX code for the subfigures in your markdown document. This is the least principled solution that takes away many of the advantages of using markdown in the first place, such as readability and portability.
2. Enable the rawAttribute and fencedCode options and type LaTeX code for the subfigures between ``` {=tex} and ```. This is more principled than using the hybrid option, leading to higher readability and portability (raw attributes are supported by other tools such as Pandoc), but the LaTeX code is still visual clutter.
3. Enable the contentBlocks option, save the LaTeX code for the subfigures to separate file images.tex, and type /images.tex surrounded by blank lines in your markdown document. This one keeps your markdown code clean, but spreads your document across multiple files, making it more difficult to navigate. Nevertheless, I like to use this solution in my documents.

Other solutions will allow you to type nice high-level markdown code but require programming effort:

4. Enable the fencedDivs option, type markdown images between ::: {.subfigure} and :::, and have a programmer prepare TeX code that will cause subfigures of appropriate size to be rendered. The general approach to styling markdown attributes such as .subfigure is described in the recent TUGboat article Attributes for Markdown.
5. Type your subfigures in any way you like and have a programmer prepare a syntax extension for the Markdown package, as described in the recent TUGboat article Markdown 2.17.1: What’s new, what’s next?, section 2.2 (User-defined syntax extensions).

Although I can give you simple examples for points 4 and 5, I find that the solutions are often specific to the needs of the publication and best solved on a case-by-case basis. If you'd like to hire a programmer, see my Fiverr and Github Sponsors profiles, or seek out other talent on our Matrix and Discord servers.

unless there's a way to automatically update markdown on Overleaf?

You can download the latest release of the Markdown package and install it on Overleaf as described in the user manual, subsection Portable Installation.

[janosh]

Thanks for the very thorough answer. This is great! 🥇

I had tried option 1 already but encountered errors trying to have a full-width figure in a 2-col doc. The figure appears twice and while it spans both columns, it overlaps with the text.

Error

<to be read again> 
                   \protect 
l.3 ...caption{Caption place holder} \end{figure}}
                                                  \markdownRendererInterbloc...
The control sequence marked <to be read again> should
not appear between \csname and \endcsname.

! Missing \endcsname inserted.
<to be read again> 
                   \protect 
l.3 ...caption{Caption place holder} \end{figure}}
                                                  \markdownRendererInterbloc...
The control sequence marked <to be read again> should
not appear between \csname and \endcsname.

## Introduction

\begin{figure*}[t!]
    \centering
    \begin{subfigure}[t]{0.5\textwidth}
        \centering
        \includegraphics[width=\linewidth]{figures/foo.pdf}
        \caption{Lorem ipsum}
    \end{subfigure}%
    ~ 
    \begin{subfigure}[t]{0.5\textwidth}
        \centering
        \includegraphics[width=\linewidth]{figures/bar.pdf}
        \caption{Lorem ipsum, lorem ipsum,Lorem ipsum, lorem ipsum,Lorem ipsum}
    \end{subfigure}
    \caption{Caption place holder}
\end{figure*}

[janosh]

If I remove the * from figure*, the errors disappear, the figure is only rendered once but the text still overlaps.

[Witiko]

It would seem that the * in figure* is understood as markdown emphasis. You may need to escape it as \* (see also section Peek Under the Hood in the README.md document of the Markdown package). Alternatively, please try options 2 and 3, neither will cause your TeX code to be interpreted as markdown by accident.

There seems to be another part to your problem regarding the overlapping text but that seems difficult to debug without knowing your document class and having a minimal working example. Perhaps fixing your first problem will also fix your second problem.

[janosh]

Thanks so much! Escaping the * solved both problems. I had also tried rawAttribute yesterday which required manually updating markdown on Overleaf since the TexLive 2022 distro doesn't contain this feature yet. Btw, what is the minimum viable set of files for a local installation? markdown.tex, markdown.sty and markdown.lua?

[Witiko]

Happy to have helped. If you want to parse YAML, you will also need markdown-tinyyaml.lua. Note that markdown.tex must be located in a directory named markdown/ due to #74.