How do I make a reference to a figure in markdown using pandoc?

Question

I'm currently writing a document in markdown and I'd like to make a reference to an image from my text.

this is my text, I want a reference to my image1 [here]. blablabla

![image1](img/image1.png)

I want to do that reference because after converting my markdown to pdf, images get placed in one or two pages after and the document doesn't make any sense.

UPDATE:

I've tried Ryan's answer in that post and I can't make it working. Apparently the code :

[image]: image.png "Image Title" 
![Alt text][image] 
A reference to the [image](#image).

should produce:

\begin{figure}[htbp] 
\centering 
\includegraphics[keepaspectratio,width=\textwidth,height=0.75\textheight]{i mage.png} 
\caption{Alt text} 
\label{image} 
\end{figure} 

A reference to the image (\autoref{image}).

instead, I obtain:

\begin{figure}[htbp]
\centering
\includegraphics{image.png}
\caption{Alt text}
\end{figure}

A reference to the \href{\#image}{image}.

I've noticed two problems :

• \label{image} doesn't appear : no reference is created.
• (\autoref{image}) becomes \href{\#image}{image} : no cross reference is detected.

And then, when I convert that to pdf it obviously doesn't link to the image. There's a link, but it doesn't link to anything.

Any help would be much appreciated!!

Sylviesylvite

Have you tried the method mentioned in groups.google.com/group/pandoc-discuss/msg/4a42442657a96414? – Helvellyn

I've tested it and it doesn't produce an autoref. weird... – Sylviesylvite

Maybe you should edit your question to include what you tried, what you got and what you want (so that it will be easier to help you). – Helvellyn

Answer 1

In pandoc you can even do:

![This is the caption\label{mylabel}](/url/of/image.png)
See figure \ref{mylabel}.

Helvellyn

This only helps if you convert to TeX but not if you also want to create HTML from the same Markdown source. – Emblematize

There are a couple of filters available to make figure reference work with all output formats pandoc-fignos and pandoc-crossref – Shenika

Unfortunately this is not a very flexible way of doing it. One cannot specify the width or height of the image this way. Is it possible to include PDFs that way? If not that would also be a downside, since it is preferable in the PDF as output case. – Histrionic

It is possible to set the width and height by using: ![This is the caption\label{mylabel}](/url/of/image.png){width=30px height=20px} – Lemberg

Answer 2

You can use the pandoc-fignos filter for figure numbering and referencing. It works with any output format -- not just LaTeX.

Add a label to the image's attributes like this:

 ![Caption.](image.png) {#fig:description}

... and then reference the figure like this:

 @fig:description

Information on how to install and apply the pandoc-fignos filter is given on its Web page. There is also the pandoc-eqnos filter for doing the same kind of thing with equations.

Estimable

I'd like to do something similar with referring to an element of an ordered list – Croydon

This also works with pandoc-crossref. See @joelostblom answer. – Hemo

Answer 3

I've had a chat with Ryan Gray after reading his answer in a similar post. Actually his solution of using :

[image]: image.png "Image Title" 
![Alt text][image] 
A reference to the [image](#image).

is only adapted when using multimarkdown.

When it comes to pandoc, the only solution to make cross references is using directly latex keywords:

[image]: image.png "Image Title"
![Alt text \label{mylabel}][image]
See figure \ref{mylabel}.

Sylviesylvite

But as Jakob said at the accepted answer, "This only helps if you convert to TeX but not if you also want to create HTML from the same Markdown source." – Croydon

For multimarkdown, is there a way to reference the figure via an automatically computed Figure number? I'd imagine something like [](#image) and then multimarkdown would replace the blank text with a number (like it does for footnotes). – Polymerism

Answer 4

With pandoc-crossref you can cross reference figures with the following syntax:

![Caption](file.ext){#fig:label}

Then reference the figure in the text similar to the citation syntax [@fig:label] and compile with --filter pandoc-crossref (needs to come before --filter pandoc-citeproc if you're using that also).

You can control the styling with e.g. \usepackage[font=small,labelfont=bf]{caption} in header-includes.

---

A neat related trick if you use \listoffigures in latex, is this lua-filter, which allows you to set a short title instead of having the entire figure legend showing up in your list of figures:

![Caption](file.ext){#fig:label short-caption='my short caption'}

then compile with --lua-filter short-captions.lua.

Shenika

--filter pandoc-citeproc should be replaced with --filter citeproc. pandoc-citeproc has been succeeded by citeproc, which is now an integral part of the pandoc distribution. – Hemo

Answer 5

Pandoc supports referencing sections (via section identifiers prefixed by #).

Comments on this open issue describe how the following workaround leverages section identifiers for generating image references in LaTeX and HTML:

<div id="fig:lalune">
![A voyage to the moon\label{fig:lalune}](lalune.jpg)

</div>

[The voyage to the moon](#fig:lalune).

The empty line before </div> is required.

Directory

A proper solution, i.e. an extension to pandoc markdown syntax to allow identifiers for pictures now finally is under way. stay tuned :) – Foltz

Answer 6

Assuming that you want PDF output of Pandoc at the end:

The best solution for inserting images and changing their attributes I found is:

\begin{figure}[H]
\includegraphics[width=0.25\textwidth, height=!]{images/path.png}
\centering
\caption{mycaption}
\end{figure}

and in my template.latex I have:

\usepackage{wrapfig}
\usepackage{float}

Other solutions cannot specify the image width or height, at least not in standard markdown. However it is often essential for something like a book or a paper to specify the dimensions of figures, except you want to configure output size of images before using them in your document. In that case you'd have to deal with different settings for those tools you use to create the images.

I recommend in case of Matplotlib to export to PDF and then use the code I posted. This will give the best image quality and highest flexibility in configuring what the image will look like in the output PDF, without having to worry about stuff.

Histrionic

Does all this latex syntax go straight into your markdown file? – Kinetic

@spinup Yes. Pandoc can handle embedded Latex stuff in your markdown file. Another advice: Export as PDF file when exporting from Matplotlib. This way Pandoc / the latex engine will not decrease image quality and you will have a scalable image, instead of something pixilated when you zoom in and out of your PDF file. – Histrionic

Answer 7

Many great awnsers here. I'd just like to draw your attention to one detail:

There must be a caption! As in:

Lore ipsum @fig:label

![Caption](file.ext){#fig:label}

And the following will not work

Lore ipsum @fig:label

![](file.ext){#fig:label}

Surakarta