Improve the HTML Theming documentation page

[cwickham]

In particular the sections used both on Guide > Documents > HTML > HTML Theming and Guide > Dashboards > Using Dashboards > Theming:

• /docs/output-formats/_theme-options.md
• /docs/output-formats/_theme-custom.md
• /docs/output-formats/_theme-variables.md

Our HTML Theming Docs have a few issues:

• ~The custom.scss example doesn't work as-is.~ Fixed in 61a0365
• There isn't a clear articulation of the pathway for users to customize their theme, e.g. start with the YAML options, if they aren't enough add a custom.scss on top of a Bootswatch theme, if that isn't enough do a standalone custom.scss theme.
• The Quarto SCSS variables, which I think cover most customizations, aren't prominent enough. At the very least they should be much closer to the section currently called Theme Options.
• The link to https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss is quite prominent, but it isn't clear what a user should do with the contents of this file (e.g. are these variables they can set, or variables they can reference?)

[mcanouil]

The link to https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss is quite prominent, but it isn't clear what a user should do with the contents of this file (e.g. are these variables they can set, or variables they can reference?)

1. Users can set them which means anything using those variables will also be modified. For instance the $gray-700 variable used in the custom.scss could be redefined to something not grey everything from Bootstrap and Quarto with rules using this variable will be impacted. It's kind of a low-level set of variables. While Quarto SASS variables are more macro.

2. They can use/reference them to harmonise components such as navbar colour, new CSS classes, etc.

[mcanouil]

Some feedback:

• https://quarto.org/docs/output-formats/html-themes-more.html
  This feels a little lost as it explains how to build properly the custom.scss that is mentioned several times and earlier. I believe explaining the structure first might help users. (Already several users were bitten by the stack order of the themes).

• https://quarto.org/docs/output-formats/html-themes.html and https://quarto.org/docs/dashboards/theming.html
  Dashboard and HTML have their own pages but they overlap massively while duplicating entries in the search. I believe the two could be united, especially if the SCSS files ends up to be one (cc @dragonstyle).
  We discussed briefly the idea of a "how to" page to describe the process of using browser inspect/developer mode to target HTML elements to set/customise (S)CSS.
  I think it would suits well in an centralised HTML theming page.

[cwickham]

We might consider generally talking about using existing Bootstrap classes, e.g. as in the example in https://github.com/quarto-dev/quarto-web/pull/948