Allow extensions to have configuration

[multimeric]

Description

Currently extensions are either enabled or disabled. For example, a filter extension is either in the filter list, or it's not. However, extensions often provide behaviour that user will want to configure in detail. Shortcodes are a bit better because they have a arguments that can be used to configure them, but ideally these arguments could be put in one central place for the whole project to avoid repetition.

I think a nice solution to this would be to extend the Quarto YAML format. I propose that items in the filters list can optionally become a one-item map whose key must be the extension name and whose value must also be a map. This is a common YAML pattern:

filters:
  - my_custom_extension:
        arg_one: 1
        arg_two: foo
  - quarto

Then, I think the lua API should gain another function that returns the extension's config. This would allow extensions like filters to easily use this information:

get_extension_config()
-- { arg_one = 1, arg_two = "foo" }

As a bonus extra, it would be cool if we could provide a schema to validate the configuration before even running the filter, but this is non-essential. e.g. in the _extension.yml:

contributes:
  filters:
    - my_custom_extension.lua
  config_schema:
    - schema.json

[mcanouil]

You can already define "configuration" and it's completely up to the extension developer.

Note that extensions don't necessarily use specific/new keys but can use the default ones (authors, toc, etc.) especially when defining a format extension. To me, your proposed design would not makes things clearer and add a constraint on extensions.

What's the issue with having the extension YAML keys alongside Quarto ones?
Would you mind elaborate on the rational?

[multimeric]

I have since played around with using the shared YAML metatadata. The advantages of a separate config are that:

• It avoids key collision, where two extensions want to read the same key. Config can be namespaced uniquely by extension name
• Config can be accessed unmodified. Currently doc.meta in lua unfortunately returns the config using Pandoc mark-up elements and not in the original YAML form
• Reading the config will be easier for extension developers. Currently I manually handle missing options and defaults, but Quarto could do this all for us
• If Quarto is aware of which config corresponds to which extension, it could automatically handle validation, documentation etc in future

[mcanouil]

Thanks.

it avoids key collision, where two extensions want to read the same key. Config can be namespaced uniquely by extension name

You can already do that as an extension developer.

I am really not sure enforcing such constraint is beneficial.
The current behaviour allows you to sequentially modify any keys by multiple extensions. If all keys are namespaced, you can't without having to modify the LUA which will make it specific.

Note that even if the team implements this, it's very unlikely to be a breaking change.

reading the config will be easier for extension developers. Currently I manually handle missing options and defaults, but Quarto could do this all for us

How Quarto could know what's the default for your extension if you don't specify them in your extension in the first place?

if quarto is aware of which config corresponds to which extension, it could automatically handle validation, documentation etc in future

That's a very far future I'm afraid but yes, I agree that if YAML validation could be extended to extension, it would be great.

[multimeric]

You can already do that as an extension developer.

Yes, so developers can choose their own config keys, but nothing stops a developer from creating a key called margin that overlaps with someone extension's key called margin. Even if I name my config key after my extension, there's no guarantee that another developer won't use that name for a different purpose.

How Quarto could know what's the default for your extension if you don't specify them in your extension in the first place?

That's exactly my point. I want extensions to have to declare their configuration schema, including key names, defaults and data types. Ideally Quarto would validate it, avoid collisions and then provide a Lua API for accessing the result. To take a real example from my own extension, this logic that stringifies and handles defaults will have to be copied into each extension I make, because it's not part of Quarto.

[mcanouil]

Thanks for the clarification.

What you are asking to enforce is not a light decision because setting such design would break 99% of existing extensions.
This goes against Posit software development design to not break things unless absolutely necessary.