Unexpected behavior when developing revealjs-plugin extension, suggest imporved docs on `config` key.

Start with the RevealJS-Plugins documentation, especially the plugin configuration section, and compare it with the linked Advanced Reveal plugin examples and _extension.yml/plugin.yml structures. Document that the config key enables user options from pres.qmd to be read, including the relevant placement and an example; the linked documentation should make this behavior explicit.

What would you like to do?

Report an issue on quarto.org

Description

I'm currently developing a revealjs-plugin extension. Currently, $ quarto create extension revealjs-plugin creates an _extension.yml folder, as described in Quarto Docs > Extensions > RevealJS-Plugins. The configuration section of this page uses the following language:

Note that when packaging an existing Revealjs plugin, you can override its default configuration using the config key within your _extension.yml file. For example, these are the overrides provided by the pointer extension:

However, this doesn't document the fact that if you don't pass a config: ext-name: <foo> key into this file, then quarto will not read the options from a users pres.qmd yaml. For example, suppose I am adding functionality to an extension, ext. I have set defaults for my added features in the extension internals, and I'm not changing the pre-existing defaults otherwise. Based on the docs, I wouldn't think of a need to pass the defaults to _extension.yml to expose these feature options to the user. However, in my pres.qmd, under format: > revealjs:, the extension relevant keys, say:

ext:
  new-feature: 
    width: 333
    height: -10
  pre-existing-feature: false

are not processed by Quarto. On the other hand, including the following in _extension.yml > contributes: > revealjs-plugins: (inline with the - name: ext key)

config:
  ext: "meaningless string"

allows for any of the aforementioned keys to work in pres.qmd. This behavior is reasonable, the _extension's config: ext key tells Quarto to listen for user options, I just think it would be helpful to document that with more explicit language.

Relatedly, the Quarto Docs > Presentations > Revealjs > Advanced Reveal #Plugins page describes using a plugin.yml file with a similar yet slightly simplified structure as compared to _extension.yml. I assume this is for personal (vs. distributed, as a Quarto extension) use of reveal plugins, but I'm mainly just including it so you know I've read it. It seems like the config: > plugin: keys work similarly in the linked source code examples.