metadata-keys for sub-keys

[zinc75]

Hi,

I'm a user and contributor of the quarto-comments extension by vgreg, which adds a custom comments: key to document frontmatter. I use it in my thesis template quarto-cnam-thesis.

I've run into a validation issue that I can't seem to get around cleanly — full discussion here: vgreg/quarto-comments#6

The extension already declares metadata-keys: [comments] in _extension.yml, which correctly whitelists the top-level comments: key. But Quarto then tries to validate its contents and rejects all sub-keys (enabled, show_author, authors, ...):

❯ quarto render example.qmd
ERROR: Validation of YAML front matter failed.
ERROR: In file example.qmd
(line 15, columns 3--10) property name enabled is invalid
14: comments:
15:   enabled: true
     ~~~~~~~~
16:   show_author: true
ℹ The error happened in location comments:enabled.

ERROR: In file example.qmd
(line 16, columns 3--14) property name show_author is invalid
15:   enabled: true
16:   show_author: true
     ~~~~~~~~~~~~
17:   authors:
ℹ The error happened in location comments:show_author.

ERROR: In file example.qmd
(line 17, columns 3--10) property name authors is invalid
16:   show_author: true
17:   authors:
     ~~~~~~~~
18:     vg:
ℹ The error happened in location comments:authors.

ERROR: Render failed due to invalid YAML.

The only workaround right now is validate-yaml: false, which kills all YAML validation project-wide — pretty heavy-handed just for a custom config block.

Any ideas on how to handle this properly? Two things that would help:

• Being able to ship a schema for the sub-keys alongside the extension (e.g. in a schema/ folder or via a new field in _extension.yml)
• Or, simpler, just having additionalProperties: true automatically applied to any key declared via metadata-keys

The second option feels like a small, non-breaking change that would unblock a lot of extension authors.

But happy to hear if there's already a way to do this that vgreg and I missed!

Thanks 🙏

[mcanouil]

@zinc75 Please don't bypass the issues templates from the issue menu picker and do follow the guidelines provided.

Issues are not to ask questions, issues are for bug reports that follow strictly the templates to ensure something can be done.
There is a discussion board to ask questions. If you don't know the category, there are also templates and guidelines.

Also, reports are to be self-contained and avoid requesting others to navigate through multiple places to understand what this is about.

Thank you for your understanding!

I'm converting this as a discussion.

[zinc75]

Sorry for that, and thanks a lot for converting if to a conversation !

[mcanouil]

comments is used by Quarto, see https://quarto.org/docs/output-formats/html-basics.html#commenting.

You should not have top-level options, especially options know to be used by Quarto to avoid conflicts and confusion with Quarto and other extensions.

Your options should be scoped.

• Scope the extensions configuration such as extensions.<name>.<option> #12894

[zinc75]

Yup, comments are scoped using Hypothesis.js, but the quarto-comments by vgreg is also for comments on PDF / LaTeX, which is very useful for academic works (it calls the todonotes package internally, which allows to comment inline in papers or thesis works, which is very useful for supervisors like me ;-)

[mcanouil]

You cannot and should not scope anything under Quarto's domain as explained.
Scope your options to be specific to your extension and not be ambiguous with Quarto and other extensions: extensions.<name>.<option>.

[zinc75]

Thanks, I better understand your first answer now. I was very helpful !

I modified accordingly the definition of config_meta and the declaration of the extension proposed by vgreg :

local config_meta = meta and meta.extensions and meta.extensions["quarto-comments"]

---
title: "Quarto Comments Demo"
format:
  html: default
  pdf:
    ...
extensions:
  quarto-comments:
    enabled: true
    show_author: true
    authors:
      vg:
        name: "Vincent"
        color_html: "#0072B2"
        color_latex: "blue!20"
      cg:
        name: "Clara"
        color_html: "#D55E00"
        color_latex: "orange!30"
---

And now it does not need the validate-yaml: false hack that vgreg proposed in its implementation ! Maybe it would be better to have another name in order not to confuse it with the Quarto's official commentsfunctionality, but this not my choice, but rather vgreg"s one as he created this extension..

Great !

Thanks a lot !