Additional theme options

[anandthakker]

Now that we've powered up themes to have substantive logic of their own, I think they're probably going to want options of their own too. Example use cases: more specialized filtering as in #274; passing in a prelude/introduction file; setting a baseurl (annoying but sometimes needed).

How about just including a themeOptions object nested within the formatter options that we already send?

Then the node api could accept themeOptions in its options, and the cli could accept a browserify-like subargs syntax or something like --theme-XXX value --theme-YYY value2.

cc @tmcw @jfirebaugh

[anandthakker]

If yall are on board does it make sense to get this into 4.0?

[tmcw]

@anandthakker I'm on board with the concept, one more question we might want to answer before diving in: how will users discover these additional arguments? Should this be something that's on the readme of the module, or should the modules provide yargs-style help by hooking into the arg parser?

[jfirebaugh]

Totally on board with this; seems like the natural next step for theme plugins.

[anandthakker]

Good question about discovering args. I like the idea of allowing but not requiring the yargs-style help.
Straw man proposal: theme modules can optionally export an object that maps each option name to a yargs-style argument descriptor, e.g.:

{
  'my-special-filter': { describe: 'My special filter.', default: false, type: 'boolean' },
  'flavor': { describe: 'Dark or light', choices: ['dark', 'light'], default: 'light'}
}

That gives us the flexibility to do whatever we want to when it comes to displaying help and parsing args in the main cli. If it's omitted, we can fall back to saying "check the theme's readme for detailed usage info and options" or whatever.

@jfirebaugh @tmcw any leanings on the subargs vs prefixed-args approach? (Or some other approach I didn't think of?)

[sbrl]

Suggestion: add simple prefers-color-scheme support to the default theme.