Add explanation on conditional code execution

[Joao-O-Santos]

The quarto documentation clearly explains how to add sections to a quarto document that are only displayed in a given input format. Yet, it is my understanding that the code in code chunks that are in those sections is always evaluated.

There are times where one would wish to have the code in those chunks only be evaluated/executed when the document is being rendered to that specific format. This happened to me when writing a document where I wanted to print a DT::datatable() when rendering to HTML and a knitr::kable() when rendering to any other format. Having the DT::datatable() chunk execute when rendering to a format other than HTML caused errors.

I found previous issues, discussions and comments addressing this, so I think I'm not the only one experiencing this problem:

• 3260
• 11724 with this comment explaining the solution.

I reckon this could be clearly and concisely explained in the documentation.

This pull request is my attempt to do just that.
I'm open to refactoring it and revising per your feedback.

Best,
J

P.S: congratulations and a giant thank you for building quarto!
I confess I was a bit skeptical at first about moving to quarto from RMarkdown, but when I started reading the quarto documentation I experienced just how much you streamlined the project rendering experience, I was able to streamline quite complicated Makefiles, and have everything more accessible to less experience collaborators.
I particularly appreciate how your documentation is editor agnostic, and does not push RStudio, and love the fact that you thought of us neovim users :)

[cderv]

Thanks for contributing a PR.

This is indeed an interesting example. The Quarto documentation aims to be as general as possible, so I worry this addition is too specific for now. It also show a use of !expr which is also knitr specific.

I wonder if we should have a specific small blog post on this trick, or an online example we could link to from the main doc.
Or a collapsible callout ?

Once quarto-dev/quarto-cli#2216 is solved, the output format will be accessible through environment variable and accessible to all engine.

When this is available, then this would have a good place in the main code I believe.

[Joao-O-Santos]

Thanks for contributing a PR.

No need to thank me.
It is I who am thankful for your hard work on quarto!

This is indeed an interesting example. The Quarto documentation aims to be as general as possible, so I worry this addition is too specific for now. It also show a use of !expr which is also knitr specific.

I see your point...if there's nothing equivalent for the other engines...it might be too specific for the general documentation.

I wonder if we should have a specific small blog post on this trick, or an online example we could link to from the main doc. Or a collapsible callout ?

If it's link from the main document, a blog post, a github gist, or anything of the sort would work.
That being said, in my humble opinion, the collapsible callout would be a better solution.
It stays in the main documentation, and should be simpler to implement than a writing a blog post or gist just for this.

Once quarto-dev/quarto-cli#2216 is solved, the output format will be accessible through environment variable and accessible to all engine.
When this is available, then this would have a good place in the main code I believe.

Moreover, when this feature is added and the documentation is updated, this section can be removed and the change in documentation can be traced back to the new feature and version.
Whereas the blog/post or gist would have to be updated to state that new versions of quarto no longer need that trick.

These are just my two cents, and I'm not familiar with the project and its guidelines.

I am so thankful that you read and considered this PR.
Please do let me know if there's anything else I can do.

I'm going to try and refactor the code to add the collapsible callout, should you choose to go that route.

Best,
J