How to reference an image?

[jurf]

The last time I used this package, I was able to reference images through auto-generated identifiers using the alt text, but that seems to have been reverted in 1c31c01.

I tried enabling autoIdentifiers, but that does not seem to affect images (see autoIdentifiers.tex in https://www.overleaf.com/read/kpbdzzttpjqh#8f7af1)

I tried enabling linkAttributes according to the example in the documentation, but that does not seem to work either (see linkAttributes.tex in the same project)

I know I can just revert 1c31c01 locally to get the original behaviour or use a \label in the caption, but I would rather ask if there is any “official” way so that I do not have to rewrite things afterwards. :)

Thanks for you work!

[Witiko]

As you noted, in commit 1c31c01, I disabled the automatic generation of LaTeX labels from the Markdown image labels. I did this because the Markdown image labels may contain not just text but also markup:

![foo _bar_](baz)

Generating LaTeX labels from text with markup would cause issues.

The "official" syntax is using the option linkAttributes and attaching an HTML identifier to the image you wish to reference:

![foo _bar_](baz){#foo-bar}

However, there is no "official" semantics to this syntax, i.e. you would need to redefine the renderers imageAttributeContextBegin, imageAttributeContextEnd, and attributeIdentifier yourself to achieve the desired effect.

[Witiko]

@jurf Admittedly, the semantics here are clear and should likely be made default. However, the general idea is that the defaults are placeholder and users should redefine them. They are not meant to be particularly stable or comprehensive. This is less of a cop-out and more of a key design consideration of the Markdown package: How any Markdown element looks should depend on the circumstances and should be redefined, all the way down to emphasis and line breaks.

In practice, authors don't like this philosophy very much: They would like stable and comprehensive defaults that work well across different LaTeX document classes. I try to provide this to a degree, although it's contrary to the philosophy.

[Witiko]

@jurf Here is an example document that you might use for inspiration:

\documentclass{article}
\usepackage{markdown}
\ExplSyntaxOn
\seq_new:N
  \l__markdown_image_identifiers_seq
\markdownSetup
  {
    linkAttributes,
    relativeReferences,
    renderers = {
      image = {
        \begin { figure }
          \begin { center }
            \includegraphics
              [ alt = { #1 } ]
              { #3 }
            \tl_if_empty:nF
              { #4 }
              { \caption { #4 } }
            \seq_map_inline:Nn
              \l__markdown_image_identifiers_seq
              { \label { ##1 } }
          \end { center }
        \end { figure }
      },
      imageAttributeContextBegin = {
        \markdownSetup
          {
            renderers = {
              attributeIdentifier = {
                \seq_put_right:Nn
                  \l__markdown_image_identifiers_seq
                  { ##1 }
              },
            }
          }
      },
      imageAttributeContextEnd = {
        \seq_clear:N
          \l__markdown_image_identifiers_seq
      },
    }
  }
\ExplSyntaxOff
\begin{document}
\begin{markdown}

![example image](example-image "An example image"){#example-image-id}

See Figure <#example-image-id>.

\end{markdown}
\end{document}

[Witiko]

I added support for image identifiers to the defaults in commit 6f3dcd0. After the release of Markdown 3.8.0, the following example document will produce same output as above.

\documentclass{article}
\usepackage[link_attributes, relative_references]{markdown}
\begin{document}
\begin{markdown}

![example image](example-image "An example image"){#example-image-id}

See Figure <#example-image-id>.

\end{markdown}
\end{document}