Enforcing the filter order with a custom format

[multimeric]

Description

I'm writing a custom format which uses a custom filter. This generally works okay, but I've noticed that my filter is definitely running before the Quarto filters, which contradicts what the docs say. Is that a mistake?

In any case, I want to force my filter to run after Quarto, because my filter needs to modify the Quarto-generated content. This works in the document YAML if I do something like this:

format:
  my-format-docx:
    filters:
      - quarto
      - my_extension.lua

However, I'm making a custom format I want to distribute. If in my _extension.yaml, I try to do the same, I get an error:

title: my-extension
author: Michael Milton
version: 1.0.0
quarto-required: ">=1.3.0"
contributes:
  filters: 
    - my_extension.lua
  formats:
    common:
      filters:
        - quarto
        - my-extension.lua

ERROR: Failed to resolve referenced filter quarto - path does not exist.
If you are attempting to use another extension within this extension, please install the extension using the 'quarto install --embedded' command.

Error: Failed to resolve referenced filter quarto - path does not exist.
If you are attempting to use another extension within this extension, please install the extension using the 'quarto install --embedded' command.
    at validateExtensionPath (file:///Users/milton.m/Applications/quarto/bin/quarto.js:59806:15)
    at resolveFilter (file:///Users/milton.m/Applications/quarto/bin/quarto.js:59781:13)
    at file:///Users/milton.m/Applications/quarto/bin/quarto.js:59652:20
    at Array.flatMap (<anonymous>)
    at file:///Users/milton.m/Applications/quarto/bin/quarto.js:59651:57
    at Array.forEach (<anonymous>)
    at readExtension (file:///Users/milton.m/Applications/quarto/bin/quarto.js:59639:8)
    at async readExtensions (file:///Users/milton.m/Applications/quarto/bin/quarto.js:59457:35)
    at async loadExtensions (file:///Users/milton.m/Applications/quarto/bin/quarto.js:59373:32)
    at async Object.extensions (file:///Users/milton.m/Applications/quarto/bin/quarto.js:59283:28)

Is this a bug? Is there a recommended way to do this?

[cscheid]

I think you're confusing two slightly different notions: that of declaring the use filter in a document, and that of declaring which filters are exposed by an extension.

The former (declaring the use filter in a document) allows you to control the order in which this happens, but needs to be done at the point of use of the filter (or extension). This is by design, because the ordering of the filters matters most often when different filters are combined, and there's no mechanism for filters to declare their "preferred order" for what other filters.

The latter (declaring which filters are exposed by an extension) has no mechanism for specifying the filter order relative to quarto's filters. In this situation you can only declare the order of the internal filters of your own extension, and those are then fixed.

The recommended way to do this is to document whether your filter needs to happen before or after quarto, and then the filter user needs to specify that in their usage. That's (understandably) unwieldy, but it's unfortunately the best design we arrived at.

[multimeric]

I don't think I'm confusing these two concepts. I understand that the contributes.filters key is a list of filters my extension exports, but that's not what I'm talking about. Rather, I'm talking about contributes.formats.X.filters, which I thought specified the default filters used by format my-format-X. I thought that this would act the same as the user Quarto config, since it works the same way. Why does the position of Quarto not make sense in the context of a specific format?

[cscheid]

Rather, I'm talking about contributes.formats.X.filters, which I thought specified the default filters used by format my-format-X.

I see. I read that too quickly, and I apologize. You're correct. I believe this is a bug, thank you!

[cscheid]

Tracking in #6759.