How to control execution order of shortcodes?

[rchaput]

Description

Hi, I'd like to know what is the execution order of the shortcodes (when are they called when rendering the document), and how to control it? Is it based on the shortcodes' names, their order of definition in the extension, their order of appearance in the document, ...?

I can't seem to understand, because I have 2 examples with a different behaviour.

Considering the following extension:

return {
    ["A"] = function (args, kwargs, meta)
        quarto.log.output("In A")
        return pandoc.Null()
    end,

    ["B"] = function (args, kwargs, meta)
        quarto.log.output("In B")
        return pandoc.Null()
    end,
}

One of my tests for an extension I'm developping shows that B is called first, independently of where it appears in the document:

---
acronyms:
  insert_loa: false
  insert_links: false
  keys:
    - shortname: RL
      longname: Reinforcement Learning
---

# Abstract {#abstract}

This paragraph mentions {{< A >}} for the first time.

And now, in this paragraph, {{< A >}} is in short form.

{{< B >}}

# Introduction {#intro}

Here, it will be again in long form: {{< A >}}.

And here in short form: {{< A >}}.

yields:

quarto render 28-shortcode-resetusage/input.qmd
pandoc 
  to: markdown
  output-file: input.md
  standalone: true
  default-image-extension: png
  markdown-headings: atx
  wrap: preserve

 metadata
  keep-yaml: false
  acronyms:
    insert_loa: false
    insert_links: false
    keys:
      - shortname: RL
        longname: Reinforcement Learning
 
In B
In A
In A
In A
In A
Output created: input.md

When writing a Minimal Working Example for this discussion, I've got another behaviour, where the order of execution depends on the usage order:

---
title: "Minimal working example for shortcode execution order"
---

First, we invoke {{< A >}}.

{{< B >}}.

Finally, we re-invoke {{< A >}}.

yields:

quarto render mwe.qmd 
pandoc 
  to: markdown
  output-file: mwe.md
  standalone: true
  default-image-extension: png
  markdown-headings: atx
  wrap: preserve
  
metadata
  keep-yaml: false
  title: Minimal working example for shortcode execution order
  
In A
In B
In A
Output created: mwe.md

I do not understand what is the difference between these 2 documents, that changes the execution order of shortcodes?

[cscheid]

It's a complicated question, and the answer is currently "shortcode execution order is undefined and unreliable". It depends on a variety of things that Quarto doesn't directly control, and so we don't promise any order.

If you want specific execution order, you currently need to turn to regular Lua filters.

[rchaput]

Thanks for the answer! It's a pity that we cannot control (or at least guarantee) the order, like we can do with Lua filters. My extension already uses filters, but I really appreciate how easy it is to use args and kwargs with shortcodes.

That would be a nice feature to have in the future, but I understand that it's difficult to implement.