RFC Reusable themes

[epage]

Cobalt supports

• A page wrapper (loaded from layouts)
• Page snippets (loaded from includes, see Define semantics for include directive #328)
• Assets (generally not loaded from layouts).

The problem is this doesn't allow easily redistributed themes

• Files are spread out, making it hard to share / reuse
• Non-theme snippets are mixed in with theme
• Theme assets are mixed in with content

Proposal

• Add _theme/<name> that contains
  • _theme.yml for theme metadata
    • theme asset permalink
    • syntax highlight theme (overrides the global syntax highlight theme)
    • custom fields (on a theme.custom variable)
  • _layouts files for page wrappers
  • _includes directory that is available from theme/ include path
  • _data directory that is available from site.theme.*
  • _sass directory for importable sass documents
  • Everything else will be treated as an asset and copied over according to the permalink (default is theme/slug.ext)
• Keep layouts folder for low-overhead themes
  • Process layouts if theme is not present
• _cobalt.yml configuration of themes
  • global theme: <slug> for setting the default for every collection
  • Per-collection theme: <slug>
  • Override mechanism: theme: <slug> is actually short-hand for theme: { "name": <slug>, "syntax-theme": <theme>, "data": <data>}

Prior Art

Jekyll

See https://jekyllrb.com/docs/themes/

Hugo

See https://gohugo.io/themes

• _layouts overrides theme
• themes can contribute to hugo new, see archtypes

[epage]

Do we expect our users to have a single theme for their entire site?

If they will have multiple themes, would it be per collection (pages, posts etc)? And/or will they want multiple themes within one collection particularly pages.

Design impact: Either we have

• a single theme auto-loaded if the _theme folder exists
• multiple themes that are specified per collection (pages, posts, etc) or in the frontmatter

[epage]

#328 took care of the breaking changes in this.

[Geobert]

What about some overloading mechanism? A global theme, and possibility to override per collection and/or per page?

[Geobert]

And we should support Jekyll's theme out of the box, so we'll get the existing huge repository. Gutenberg has so many themes thanks to Hugo's.

EDIT: or enhance the Jekyll conversion to convert themes as well

[epage]

A global theme, and possibility to override per collection and/or per page?

Yes, we should support a global theme and allow it to be overridden per-collection. I'd like to avoid per-page unless there is a strong use case for it. This means the directory hierarchy would be _theme/<name>/<data>.

And we should support Jekyll's theme out of the box, so we'll get the existing huge repository. Gutenberg has so many themes thanks to Hugo's.

EDIT: or enhance the Jekyll conversion to convert themes as well

The challenge is in the differences between us on Jekyll. I agree about the conversion utility supporting themes.

[berkus]

see archtypes

archetypes, and these are immensely useful in any non-trivial static site.