Embedding a shared filter in a custom format filter

[david-hodge]

Description

I'm trying to create some new custom formats, which all use some shared lua filters. I've worked out how to create the filter extension, but I cannot get the --embed command to work.

I tested it by starting with this structure: (I also tried the same as below but via quarto create extension, which makes everything two directories deeper)
quarto-test/
│
├─ filter-a/
│ ├─ _extension.yml
│ └─ a.lua
│
├─ format-b/
│ └─ _extension.yml
│
├─ format-c/
│ └─ _extension.yml
│
└─ test-proj/
├─ _quarto.yml
├─ index.qmd
└─ _extensions/ **
├─ filter-a/ **
│ ├─ _extension.yml **
│ └─ a.lua **
├─ format-b/ **
│ └─ _extension.yml **
└─ format-c/ **
└─ _extension.yml **

Where I manually created the filter-a, format-b and format-c folders.
Then I navigated into test-proj\ tried to quarto add ../filter-a/ which worked fine.
However it won't let me quarto add ../format-b since the _extension.yml for format-b contains a

filters:
    - filter-a

The only way I can get it to embed is to first remove mention of filter-a inside format-b, then embed filter-a inside format-b (which adds a further nested _extension folder deep inside format-b). Then later I did add format-b to test-proj but the filter-a isn't getting picked up. Does anyone has an actual example of a filter embedded inside a format they can point me too perhaps?

I'm in Quarto 1.8.24 in Fedora 42.

[mcanouil]

What's the goal of the embedded filter? Is it supposed to be used by end-users? Is it only used internally by your format extension?

Note that without a concrete "working" example, it's hard to provide accurate help.
Could you share a small self-contained "working" (reproducible) example to work with, i.e., a complete Quarto document or a Git repository? The goal is to make it as easy as possible for us to recreate your problem so that we can fix it: please help us help you! Thanks.

[david-hodge]

Thanks. The filter is designed to inject some code into the html to load some css files; load some js scripts and add an html button. The formats will provide things like navbar structure etc.. but the filter provides some content manipulation.

Here's a minimal repo, I think: https://github.com/david-hodge/format-c

I've created a totally basic filter which just injects some text into the html, and then I'd used quarto add with the --embed flag to embed my filter-a inside format-c. However, the filter doesn't seem to run.

(I think what I'm trying to do makes sense, but I could always add an extra burden to the user and get them to install format-c and also install filter-a and then just load filter-a filters via the template.qmd inside format-c?)

Thanks.

[david-hodge]

I think I understand it now. It looks like I was making two errors: one was that my contributes: code was naming the new custom format and not just saying "html".

The other is that I cannot already include the filters: statement in the custom format _extension.yml file before I have installed the filter, else it seems to get upset. I presume because the format-c extension cannot have something embedded inside it if it currently contains broken references (even if the embedded is trying to fix them!).

I removed the filter: code from the format-c _extension.yml and them was able to --embed the filter-a inside format-c. And then I re-added the filter: code to the format-b definition.

Thanks for your time, I will go and try and fix my minimal example now to make it work.

[mcanouil]

Thanks for the update.
Keep us posted if you still have issues, we'll dive into it (or if everything works).

[david-hodge]

Thanks, yep I got it working now. In case someone comes across this post in the future:

Lesson 1

The custom format (format-c in my case) definition in _extension.yml needs to compile properly before we try to embed the sub-filter. So first embed the filter with quarto add path/to/filter/ --embed format-c and only then add filters: code into _extensions.yml for format-c. i.e. don't get ahead of yourself

Lesson 2

The custom format yml should say:

contributes:
  format:
    html:

Note html not format-c or format-c-html.

[mcanouil]

Glad you got it to work!

In the case it's for public consumption, don't hesitate to submit it to my extensions listing at https://m.canouil.dev/quarto-extensions/about.html