named themes

[Fil]

Adds a themes project configuration option, which lists all the available themes by name (the name is the key).

A theme is an object with a style property indicating the a local file (typically docs/custom.css) to use as the (only) stylesheet for this page.

For example, to reference a new solarized theme, create a docs/solarized.css stylesheet and set:

themes: {
  solarized: { style: "docs/solarized.css" }
}

Themes can be referenced in any page by specifying the theme option in the front-matter:

---
theme: solarized
---

Any theme that is used on (at least) one page in the project gets built as _observablehq/{name}.css with rollup.

---

Some considerations:

• using an object allows faster lookups than Array.find; not that it would be slow anyway, but it's more clumsy to write the code with Array.find. (I considered a Map but it's not serializable, a desirable property for config files.)
• the theme is itself an object, not just the style string; that is because we'll probably want to extend the notion of themes to include more things; maybe a title and an attribution (?), but most certainly we'll want to have something like "an external stylesheet" or "a list of external stylesheets". This will allow to make the google fonts URL be part of the theme. I've reserved this for a follow-up PR.
• with this approach you cannot stack "several themes" on a page: it's only one theme, one css, one entry point. This allows to build (rollup) a single optimized file, and avoids having to guarantee that the different sheets are compatible: the onus is on the docs/{name}.css to figure this out, not on the system (and, I figured that if people want a meccano of css files to pick from, they would use link elements, or we could add a different mechanism to specify "additional css" independently of this mechanism)
• writing the documentation forced me to clarify that "dark" and "light" are not the same as these themes, so I renamed them to schemes, which is probably correct. But we could go the other way around, use theme for dark mode, and some other word (style…?) for this feature.
• The documentation about styles and themes will be long, so I split it out into its own page, which will need a whole section about css variables.
• One thing that I'm confused about (independently of this PR) is what we want to happen when there is NO docs/style.css
• Also confused about dashboard.css; should it be presented as a built-in theme, since it's only 2 rules does it correspond to expectations?

closes #60

[mbostock]

I don’t like the “scheme”/“theme” distinction. It’s too similar (and I don’t understand what a “scheme” is now by reading this…). Edit: I guess this is suggesting that a “scheme” is specifically a “color scheme” which is part of a “theme”. Saying “color scheme” would be clearer, but if themes are composable, we don’t need to make a distinction.

Also… I want to have composable themes, so that you can compose e.g. a set of colors with a set of fonts.

[Fil]

Thinking out loud for now (I'll work on that tomorrow):

If we do composable themes, then dark mode can be a theme again! It should be easy to accept theme to be either a string or an array of strings, and then apply that with the same logic I've already coded.

It would probably mean that if you have three themes you will load 3 rollup'd styleshhets, not one that concatenate the three. I'd still want to not use the default style if I specify a theme; but then if the default theme has a name too, I
can opt-in and say:

---
theme: default, comic-sans, solarized
---

or

---
theme:
  - default
  - comic-sans
  - solarized
---

[mbostock]

The default theme is currently called “auto”, not default. And it doesn’t mean loading multiple bundles. I looked at doing this previously (and decided it wasn’t worth the effort… but I’m fine revisiting), and it just means turning the theme option into an auto-generated stylesheet.

So, if you have the default

theme: auto

then you get the default stylesheet

@import url("observablehq:theme-auto.css");
@import url("observablehq:default.css");

but if you change the theme to light

theme: light

then you get

@import url("observablehq:theme-light.css");
@import url("observablehq:default.css");

and if you want multiple themes

theme: [comic-sans, solarized]

then you get

@import url("observablehq:theme-comic-sans.css");
@import url("observablehq:theme-solarized.css");
@import url("observablehq:default.css");

This approach would mean some redundancy in the generated CSS bundles if you use different themes on different pages, but I think that’s totally acceptable as an initial solution (and we could do code-splitting if we wanted to avoid that in the future).

[mbostock]

I guess we also have to decide how you could do a custom theme… like would you say theme: foo.css or theme: ./foo.css to refer to a foo.css file, or would you say theme: foo and we’d let a local foo.css file take precedent over observablehq:theme-foo.css if it exists? Or would we require theme: observablehq:foo to refer to a built-in theme? (Seems like a mouthful…)

[Fil]

superseded by #442 #443