Epic: quarto.org Style Guide

[cwickham]

Are there smaller changes that we could make globally on the website that would make user’s lives easier?

• Use code language (e.g. no bare ``` code cells) for every code cell

• Make more use of filename to disambiguate context

• Always include all parents of keys in YAML chunks (or a guide on when it is OK to only use a partial hierarchy)

• When should the --- be included in a YAML header chunk?

• What do we call YAML keys (keys or options)?

• Do we talk about .class or class?

• Do we include prompt characters e.g.> on R Console, or $ on Terminal?

• [ ] https://github.com/quarto-dev/quarto-cli/issues/6220

• [ ] https://github.com/quarto-dev/quarto-cli/issues/6161

There is a style guide (internally hosted on Confluence) for the docs for Posit's pro products. This could be referenced for most general matters. The style guide for quarto.org would focus on how we talk about Quarto, and conventions used in the source for quarto.org.

[mcanouil]

Do we include prompt characters e.g.> on R Console, or $ on Terminal

This would mess up the ability to copy code, so I would really avoid adding characters like that. I think the best is to use file name as done in some parts to state the context as you suggested.

Do we talk about .class or class?

That is a bit tricky. In fenced divs, it implies the use of the brackets. (I am personally in favour of always using brackets thus the dot syntax)

The tricky part is in classes for code cells, i.e., classes: firstClass .secondClass

[cwickham]

This would mess up the ability to copy code, so I would really avoid adding characters like that. I think the best is to use file name as done in some parts to state the context as you suggested.

I agree. But there are some examples on quarto.org that do include it.