Can a Quarto Custom Format have a filter embedded within it?

[jtlandis]

Description

I am just trying to wrap my head around using extensions and the purpose of embedding extensions. I have a format that I would like to use pretty consistently. I know that I could also make a custom filter, but I do not know if these must be set in the qmd's document's yml header or if I have a filter embedded in another format and the document's header automatically uses the default of the custom format if the filter will be used.

[multimeric]

A custom format can specify a set of default filters, yes. You list them under contributes.format.X.filters. There is an example of this here in the documentation: https://quarto.org/docs/extensions/formats.html#common-metadata.

Does that help?

[cderv]

Also, custom format can embed an existing extensions. More of this here: https://quarto.org/docs/extensions/formats.html#extension-embedding

This means a custom formats can rely on another extensions - like a filter & shortcode extension

[jtlandis]

Okay, these were the resources I was viewing before and became confused about what "common metadata" meant. My embedded filter did not work until I removed the .lua from the common meta data in the format's _extension.yml file. A second question, I know it is documented that if we want a filter to run before quarto's default filters, we need to specify that in the document's .yml header. Can the order of filters still be controlled when a document uses a format with an embedded filter?

--- EDIT (clarity) ---

[mcanouil]

See:

• Enforcing the filter order with a custom format #6747

[jtlandis]

This may be worth its own issue, but it is related to my last comment. I'm finding that contrary to this documentation on filter execution order, it doesn't seem that extension filters are run after quarto's default filters.

For more context, I have a simple filter in development under jtlandis/auto-eq. So far all it does is print the Para elements of the document to the console. What I am seeing is that when this filter extension is available, a yml header like the following

---
filters:
  - auto-eq
---

$$
1 + 1 = 2
$$

is equivalent to

---
filters:
  - auto-eq
  - quarto
---

$$
1 + 1 = 2
$$

which is different from

---
filters:
  - quarto
  - auto-eq
---

$$
1 + 1 = 2
$$

when comparing between the logging outputs.

[cscheid]

Sorry, but can you point to where our documentation claims what you're stating wrt filter evaluation order? (more precisely than just the page, that is)

[multimeric]

By default, user filters are run after Quarto’s built-in filters. For some filters you’ll want to modify this behavior.

https://quarto.org/docs/extensions/filters.html#:~:text=By%20default%2C%20user%20filters%20are%20run%20after%20Quarto%E2%80%99s%20built%2Din%20filters.%20For%20some%20filters%20you%E2%80%99ll%20want%20to%20modify%20this%20behavior.

I noted this behaviour in my issue as well.

[cscheid]

Thank you, that's definitely 100% wrong, a really bad typo.

[cscheid]

This is fixed now - thanks for bringing this up (even if repeatedly!). We appreciate it.

[cscheid]

@multimeric Your issue was related to an actual code bug, which confused me. I apologize! For future reference, this is why we ask often to keep separate bugs in separate issues! It's so easy to miss these things when having to track multiple questions.

[jtlandis]

Seeing that #6759 is the actual tracking issue for declaring when embedded filters are run and the documentation is consistent, I will go ahead and close this discussion. Thank you @cscheid, @multimeric @cderv and @mcanouil for all your contributions!