We can have citations inside figure captions (plus bonus migration script)

[danmackinlay]

Description

As noted on my quarto blog,
citations inside figure captions do not work, we need to use figure divs
e.g. this is no good

![See @HallCan2022 — the attention economy of road signs](/images/science.abm3427-fa.avif)

But this is fine:

:::{#fig-hallcan2022}
![](/images/science.abm3427-fa.avif)

See @HallCan2022 — the attention economy of road signs
:::

For these to come out nicely as Figures with captions, need to give all our figure divs an id starting with #fig-. I wrote a python script which does this automatically by inventing an id inspired by the filename, so that I could migrate my figures from hugo:

#!/bin/sh
#
import re
import sys

def add_figure_ids(markdown_body):
    # Regular expression to match figure blocks with .figure class anywhere in the class list
    figure_block_pattern = re.compile(
        r':::\{([^}]*)\.figure([^}]*)\}\n(.*?)\n:::',
        re.DOTALL
    )

    # Function to generate a figure ID from the image source
    def generate_figure_id(match):
        img_src = re.search(r'!\[.*?\]\((.*?)\)', match.group(3))
        if img_src:
            img_name = re.sub(r'^images/', '', img_src.group(1)).split('/')[-1].split('.')[0]
            sanitized_img_name = re.sub(r'[^a-zA-Z0-9]', '-', img_name).lower()
            fig_id = f'fig-{sanitized_img_name}'
            other_classes = match.group(1) + " .figure" + match.group(2)  # Keep the ".figure" class
            return f':::{{#{fig_id} {other_classes.strip()}}}\n{match.group(3).rstrip()}\n:::'
        return match.group(0)

    # Apply the transformation to each figure block
    modified_markdown_body = re.sub(figure_block_pattern, generate_figure_id, markdown_body)
    return modified_markdown_body

def process_markdown_file(file_path):
    # Read the Markdown file
    with open(file_path, 'r') as file:
        content = file.read()

    # Check if the original file ends with a newline
    ends_with_newline = content.endswith('\n')

    # Separate the YAML header and Markdown body
    parts = content.split('---', 2)
    if len(parts) == 3:
        yaml_header = parts[1].strip()
        markdown_body = parts[2].strip()
    else:
        yaml_header = None
        markdown_body = content.strip()

    # Modify the Markdown body
    modified_markdown_body = add_figure_ids(markdown_body)

    # Write the modified content back to the file
    with open(file_path, 'w') as file:
        if yaml_header:
            file.write(f'---\n{yaml_header}\n---\n\n')
        file.write(modified_markdown_body)
        if ends_with_newline:
            file.write('\n')

if __name__ == '__main__':
    if len(sys.argv) != 2:
        print('Usage: python process_markdown.py <file_path>')
        sys.exit(1)

    file_path = sys.argv[1]
    process_markdown_file(file_path)

Initially I tried to write it as a lua pandoc filter thinking the parsing woudl be more principled than hacky regexes..., before discovering that pandoc is not idempotent when applied to markdown.

Hoping this helps someone.

[cderv]

citations inside figure captions do not work

As you have a project setup already, can you try if this work with bare pandoc ?
Do they process citation in caption already ?

For these to come out nicely as Figures with captions, need to give all our figure divs an id starting with #fig-

In this case, we take over pandoc to process caption and create the figure, and this process handle citation.

[cscheid]

Thanks for the report (and post!) but I'm having trouble reproducing your first point. I get a broken video because I don't have the media file, but the citation is resolved correctly, even without fig-. Can you give us a full example where that fails? Thanks!

test.qmd

---
title: test citation in caption
bibliography: science.bib
---

![See @Wu2018 — the attention economy and the law](/images/science.abm3427-fa.avif)

science.bib

@article{Wu2018,
  title={Blind spot: The attention economy and the Law},
  author={Wu, Tim},
  journal={Antitrust LJ},
  volume={82},
  pages={771},
  year={2018},
  publisher={HeinOnline}
}

output

[danmackinlay]

well... color me surprised @cscheid I believed I did test that at some point and had persuaded myself it didn't work. Did it not work some time in the past, and the upgrades fixed it, or was I always delusional? Hard to say.

[cscheid]

This should have worked right from the start, because there's nothing special about the way the citation is processed. Maybe you tried something like

```{r}
#| fig-cap: "See @Wu2018 — the attention economy and the law"
...
```

And that might not work. (And, the easy way to make this work in general is to use the div syntax I've just pointed you to.)