Best way to do a project "filter"?

[andrewpbray]

Description

I have a custom project type that adds a bunch of functionality to university course websites. One piece of that functionality is the ability to schedule documents for publishing. I am trying to figure out the best way to pull that piece out into a more narrowly scoped extension that users can add to their website to get just the scheduled document functionality.

I've started building this as an extension where _extension.yml looks like:

contributes:
  project:
    project:
      type: scheduled-docs
      pre-render:
        - write-draftlist.ts
      post-render:
        - rm-draftlist.ts
    metadata-files:
      - scheduled-docs_files/draftlist.yml

The problem is that I don't want users to have to use project: type: scheduled_docs in their _quarto.yml. Scheduled docs feels like singular functionality (akin to a filter), not a full project type (akin to a custom format). Could this functionality be addable inside an existing Project Type?

I've come up with two alternatives:

1. Manually modify _quarto.yml

In my documentation I could instruct users to add the pre-render, post-render, and metadata-files keys to their _quarto.yml. The downsides there are that the functionality is now brittler and it requires them to handle the paths themselves (i.e. _extensions/scheduled-docs/write-draftlist.ts).

2. Package it up as a metadata file

I could instead make an ext.yml file in my extensions dir that looks like:

project:
  pre-render:
    - _extensions/scheduled-docs/write-draftlist.ts
  post-render:
    - _extensions/scheduled-docs/rm-draftlist.ts
    
 metadata-files:
   - scheduled-docs_files/draftlist.yml

then users would just have to add one line to their _quarto.yml: metadata-files: "_extensions/scheduled-docs/ext.yml". The downsides here is that this really does feel like a hack on the existing extension system and it shows in the fact that the paths in ext.yml are relative to _quarto.yml.

---

I've come to think of filters as adding functionality to a document and a custom format as a batch of meta data, filters, et al. You can add many filters to a document and the functionalities add, but you can't add multiple custom formats to the same document.

In essence I guess I'd like a project "filter". It seems like we're really close with the existing functionality around Project Types except you can only have one Project Type per project. Would this be as easy as allowing project: type to take an array and fun through those metadata merges in order? Or is that muddling the notion of a "custom format" with a "filter"?

Maybe a separate key like:

project:
  type: website
  extensions:
    - scheduled-docs
    - some-other-extension

?

[jimjam-slam]

I think the related (or reframed?) question I've been pondering is, "What advice do I give to users who want to use my custom format or project in conjunction with another custom format or project?" Right now it's basically, "Copy the settings from the extension definition and merge them yourself," but that's definitely asking users to pop the hood!

[andrewpbray]

Yep, that's a good way to phrase it!

Here is that scheduled-docs extension, currently using approach 1.

https://github.com/qmd-lab/scheduled-docs

I've thought of a third way this could be done using existing tooling...

3. Use a project profile

I haven't tried it yet, but it should work to make a project profile with the pre-render, post-render and metadata-files contributions. The problem, I think, is distribution. I believe this would require quarto use template instead of quarto add. It'd also prevent quarto embed, which is a bummer since the genesis of this refactoring was to separate out this functionality in order to be able to then embed it within my other project template.