Document PanelLayout custom nodes

[cderv]

It is currently not mentioned in Custom AST node highlight:

• https://quarto.org/docs/prerelease/1.3/ast.html

[cscheid]

That's on purpose - PanelLayout nodes have really ugly internal behavior and we don't want to document them yet.

(With that said, we should document some other nodes like FloatRefTarget; I'm much more confident that it is ready.)

[cderv]

That's on purpose - PanelLayout nodes have really ugly internal behavior and we don't want to document them yet.

Got it. But shouldn’t we put this in writing? Maybe include it somewhere in our advanced developer documentation, or even a brief post on the dev blog? That way, it’s documented. I believe all forms of communication are valuable, and it’s important for us to be transparent. For example: “PanelLayout shouldn’t be targeted in Lua filters since there’s no guarantee it won’t change.” End of story.

It seems like Custom AST nodes fall into two groups:

• Internal Nodes: meant only for internal use, not for external Lua filters.
• User-facing Nodes: designed to create or modify custom Quarto components within external Lua filters.

I wasn’t totally sure if PanelLayout fit this exactly, so I didn’t frame the issue that way initially. But ultimately, the key point is having this clearly explained in the advanced documentation.

[cscheid]

Got it. But shouldn’t we put this in writing?

That is a great idea that I agree with, and hadn't considered before!

[cscheid]

How about we reopen this with a more general goal of documenting Quarto's extended AST nodes?

[cderv]

Yes definitely ! I am glad speaking thought out loud (or rather writing them in the open) can help !