Crossreference subfigures inside figure caption only using subref-label

[skwde]

Description

I checked the docs, especially

• https://quarto.org/docs/authoring/cross-reference-options.html#references
• https://quarto.org/docs/authoring/cross-references-custom.html
• https://quarto.org/docs/authoring/cross-references-divs.html

but have not found a way to crossreference subfigures in captions just as "a" instead of "1a".
Note, outside the figure crossref like "1a" is fine.

How do I do that?

Here is a minimal working Example:

---
format:
  pdf
---

::: {#fig-test layout-nrow=3}

![test1](https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%2Fid%2FOIP.pSwhjfLi92oR5glrmiogmgHaHa%3Fpid%3DApi&f=1&ipt=4f743eb3c4a8671755700b94ceed8dc5043805007400ca584b7b0befaefb7096&ipo=images){#fig-test1 height=200px}

![test2](https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%2Fid%2FOIP.pSwhjfLi92oR5glrmiogmgHaHa%3Fpid%3DApi&f=1&ipt=4f743eb3c4a8671755700b94ceed8dc5043805007400ca584b7b0befaefb7096&ipo=images){#fig-test2 height=200px}

![test3](https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%2Fid%2FOIP.pSwhjfLi92oR5glrmiogmgHaHa%3Fpid%3DApi&f=1&ipt=4f743eb3c4a8671755700b94ceed8dc5043805007400ca584b7b0befaefb7096&ipo=images){#fig-test3 height=200px}

**Test** The first image is @fig-test1, the second image is [-@fig-test2], and the third image is [@fig-test3].

:::

See @fig-test and especially @fig-test2 for the second image.

[pratikrath126]

Hey! That's a great question about Quarto's cross-referencing. For subfigures, Quarto usually prepends the main figure number. To get just the subref label (like 'a') in the caption, you might need to look into using a custom filter or adjusting the crossref YAML options if they support 'subref-only' styling. Have you tried looking into the Pandoc crossref options as well? Sometimes the solution lies in the underlying Pandoc processing. Hope you find a clean way to do it!

[mcanouil]

There is no fine grained control like that.

You can change the style of the cross-reference but it will apply to all references.

The design assumes subfigures are children of a panel and should include the parent number for disambiguation (e.g., “Figure 1a” vs “Figure 2a”). Changing this requires custom logic because the crossref system resolves references using the combined numbering

You usually don't reference elements in themselves.
Either hardcode the sub-figure prefix or maybe use raw LaTeX if you are only targeting that format.

If you want to make a Lua filter, this would be way more involving.
You will need to walk through the AST to post-process Quarto cross-references while having to handle context (in caption vs. In plain text). You would also need to know if the reference is itself or a reference to something else otherwise you will create ambiguity.

[mcanouil]

Here is one approach. Note that the number comes from LaTeX/Typst, so you need to make changes there in addition to the Lua filter.

As usual with LaTeX, it's a nightmare to do anything, so the below Lua filter is for HTML/Typst only.

---
format:
  html: default
  typst: default
filters:
  - path: subfig-ref.lua
    at: post-quarto
---

::: {#fig-test layout-ncol=3}

::: {#fig-test1}
{{< placeholder 200 200 >}}

Test 1
:::

::: {#fig-test2}
{{< placeholder 200 200 >}}

Test 2
:::

::: {#fig-test3}
{{< placeholder 200 200 >}}

Test 3
:::

**Test** The first image is @fig-test1, the second image is [-@fig-test2], and the third image is [@fig-test3].

:::

See @fig-test and especially @fig-test2 for the second image.

::: {#fig-testa layout-ncol=3}

::: {#fig-testa1}
{{< placeholder 200 200 >}}

Test 1
:::

::: {#fig-testa2}
{{< placeholder 200 200 >}}

Test 2
:::

::: {#fig-testa3}
{{< placeholder 200 200 >}}

Test 3
:::

**Test** The first image is @fig-testa1, the second image is [-@fig-testa2], and the third image is [@fig-testa3].

:::

See @fig-testa and especially @fig-testa2 for the second image.

--- subfig-ref - Filter
--- @module subfig-ref
--- @license MIT
--- @copyright 2026 Mickaël Canouil
--- @author Mickaël Canouil
--- @version 0.1.0
--- @brief Pandoc AST filter for subfig-ref.
--- @description Strip parent prefix from subfigure cross-references inside
---   their parent figure. At post-quarto, Quarto replaces Div IDs/classes with
---   __quarto_custom_* attributes. The Div handler is not called for these
---   custom elements, so the filter walks the AST manually via a Pandoc handler.

local function is_float_ref_target(el)
  return el.t == "Div" and el.attributes["__quarto_custom_type"] == "FloatRefTarget"
end

local function has_nested_float_ref(div)
  local found = false
  div:walk({
    Div = function(inner)
      if is_float_ref_target(inner) then
        found = true
      end
    end
  })
  return found
end

--- HTML: Link content is [Figure, NBSP, 1, Space, (, a, )].
--- Strip everything before the opening "(" Str.
local function strip_html_link_prefix(link)
  if not link.classes:includes("quarto-xref") then
    return nil
  end

  local paren_idx = nil
  for i, inline in ipairs(link.content) do
    if inline.t == "Str" and inline.text:match("^%(") then
      paren_idx = i
      break
    end
  end
  if paren_idx == nil then
    return nil
  end

  local new_content = pandoc.Inlines({})
  for i = paren_idx, #link.content do
    new_content:insert(link.content[i])
  end
  link.content = new_content
  return link
end

--- Typst: Reference is RawInline("#ref(<id>, supplement: [") + content + RawInline("])").
--- Replace the whole construct with RawInline("#subref(<id>)").
local function strip_typst_prefix(inlines)
  local new = pandoc.Inlines({})
  local i = 1
  local changed = false
  while i <= #inlines do
    local el = inlines[i]
    if el.t == "RawInline" and el.format == "typst" then
      local ref_id = el.text:match("^#ref%((<fig%-.->), supplement: %[$")
      if ref_id then
        local j = i + 1
        while j <= #inlines do
          if inlines[j].t == "RawInline" and inlines[j].format == "typst" and inlines[j].text:match("^%]%)$") then
            break
          end
          j = j + 1
        end
        if j <= #inlines then
          new:insert(pandoc.RawInline("typst", "#subref(" .. ref_id .. ")"))
          i = j + 1
          changed = true
        else
          new:insert(el)
          i = i + 1
        end
      else
        new:insert(el)
        i = i + 1
      end
    else
      new:insert(el)
      i = i + 1
    end
  end
  if changed then
    return new
  end
  return nil
end

local function process_parent_figure(div)
  if quarto.doc.is_format("html") then
    return div:walk({
      Link = strip_html_link_prefix
    })
  end

  local strip_prefix
  if quarto.doc.is_format("typst") then
    strip_prefix = strip_typst_prefix
  else
    return div
  end

  return div:walk({
    Plain = function(plain)
      local result = strip_prefix(plain.content)
      if result then
        plain.content = result
        return plain
      end
      return nil
    end,
    Para = function(para)
      local result = strip_prefix(para.content)
      if result then
        para.content = result
        return para
      end
      return nil
    end
  })
end

local function process_blocks(blocks)
  local changed = false
  for i, block in ipairs(blocks) do
    if is_float_ref_target(block) and has_nested_float_ref(block) then
      blocks[i] = process_parent_figure(block)
      changed = true
    elseif block.t == "Div" then
      if process_blocks(block.content) then
        changed = true
      end
    end
  end
  return changed
end

--- Inject format-specific header content for \subref / #subref support.
local function add_header_includes(meta)
  local raw_block = nil

  if quarto.doc.is_format("typst") then
    raw_block = pandoc.RawBlock("typst", [[#let subref(target) = {
  link(target, context {
    let idx = quartosubfloatcounter.at(query(target).first().location()).first() + 1
    [(#numbering("a", idx))]
  })
}]])
  end

  if raw_block == nil then
    return nil
  end

  local includes = meta["header-includes"]
  if includes == nil then
    includes = pandoc.MetaList({})
  end
  includes:insert(pandoc.MetaBlocks({ raw_block }))
  meta["header-includes"] = includes
  return meta
end

function Pandoc(doc)
  local meta_changed = add_header_includes(doc.meta)
  local blocks_changed = process_blocks(doc.blocks)
  if meta_changed or blocks_changed then
    return doc
  end
  return nil
end