#internal/themes

#internal/themes

Package themes is the theme registry: the stylesheets a built site can be painted with, and the metadata each one carries.

A theme is its CSS file. The registry is therefore the listing of the embedded stylesheets rather than a second list kept in step with them, so every place that validates or enumerates a theme reads [List].

#Framework themes

A theme's companion JSON may declare a framework block, and then the theme is not a whole stylesheet: it is an overlay on top of a framework whose sheets ship in a dependency. tinymoon is the one such theme -- selfdoc consumes the framework rather than imitating it, so the palette, the reset and the faces are the framework's, and the file in this package carries only what is selfdoc's. The overlay still restates a good deal of component styling, because the emitters still produce selfdoc's own class surface rather than the framework's markup shapes; that restatement goes when the emitters migrate.

Three consequences the rest of the build reads through this package:

- [CSS] returns the composed stylesheet -- the framework's sheets, in the order its markup contract requires, then the overlay. The framework bytes are shipped as-is; nothing here rewrites them. - [Assets] names the non-CSS files that have to travel with the stylesheet, and [CSSRel] says where the stylesheet is written relative to a site root. The framework's @font-face rules address ../fonts/, so the stylesheet goes in css/ with fonts/ beside it -- the layout inside the framework's own asset tree, preserved. - [Modules] is the ES modules a page under the theme imports: the closure of the entry points the framework block declares, computed from the framework's own sources. A declared list would be a second copy of a fact the sources already state, and the breakage when it fell behind would be a page importing a module the site does not carry.

#DefaultCSSRel

const DefaultCSSRel = "style.css"

DefaultCSSRel is where a plain theme's stylesheet is written, relative to a site root.

#FrameworkCSSRel

const FrameworkCSSRel = "css/style.css"

FrameworkCSSRel is where a framework theme's stylesheet is written. The directory is not decoration: the framework's font URLs are ../fonts/, so the sheet has to sit one level in with fonts/ as its sibling.

#ModulesDir

const ModulesDir = "js"

ModulesDir is where a framework theme's ES modules are written, from the payload root.

#Asset

type Asset struct

Asset is one file that travels with a theme's stylesheet.

The source is a path inside an [fs.FS] rather than a filesystem path, because the framework's assets are embedded in the framework's own module: there is no directory on disk to copy from. A build stage writes the asset by reading [Asset.Bytes] and handing them to the effects handle, so the write is declared like every other one.

#Metadata

type Metadata struct

Metadata is everything a page renderer needs to know about a theme beyond its stylesheet: how the faces are loaded, what the accent colour is, which highlighting styles the code blocks use, and where the stylesheet itself is written.

Name and CSSRel are computed rather than declared: every page renderer already carries the metadata, so carrying the theme's identity and the address of its stylesheet in the same value saves threading two more parameters through every wrapper.

#Framework

type Framework struct

Framework is the framework block a theme declares: a package whose sheets the theme composes over, plus the asset directories and the ES module entry points that have to travel with the composed stylesheet.

#FrameworkOf

func FrameworkOf(name string) (*Framework, error)

FrameworkOf returns the framework block the named theme declares, or nil for a theme that is a whole stylesheet of its own.

Half a declaration is a broken theme rather than a theme with defaults: a block naming no package, or no sheets, is refused.

#FrameworkSheetsCSS

func FrameworkSheetsCSS(name string) (string, error)

FrameworkSheetsCSS returns the framework sheets a theme composes over, concatenated in the declared order, each under a banner naming its source.

Empty for a theme that declares no framework. The bytes are the framework's own: they are read and joined, never rewritten, so the hash of the result pins the framework version that produced it.

#Modules

func Modules(name string) ([]string, error)

Modules returns every framework module a page under this theme loads, sorted.

The theme's framework block names entry points -- the modules the page's own script imports by name. Their transitive imports are computed here from the framework's own sources rather than declared, because a declared list is a second copy of a fact the sources already state, and the breakage when it falls behind is a page that imports a module the site does not carry.

The framework ships far more than a documentation page uses (its whole module tree is an order of magnitude larger than this closure), so the closure is also what keeps the payload to what is really loaded.

Empty for a theme that declares no framework, or one whose framework block names no modules.

#Assets

func Assets(name string) ([]Asset, error)

Assets returns the files that have to travel with a theme's stylesheet and are not the stylesheet, each with the site-relative address it is written at.

One directory per kind the framework block names -- the @font-face rules are the only thing in the sheets that addresses anything outside them -- plus the ES modules a page imports, which are the closure of the block's declared entry points rather than the framework's whole module tree. Empty for a theme that declares no framework. Destinations keep the layout the framework uses, because the sheets and the modules address each other by relative URL.

#List

func List() []string

List returns every theme name this build ships, sorted.

A theme is its CSS file, so the listing of the embedded stylesheets is the registry -- there is no second list to keep in step with it.

#Meta

func Meta(name string) (Metadata, error)

Meta returns the metadata for the named theme: the contents of its companion {name}.json merged over the defaults, plus the computed name and stylesheet address.

A theme with no companion JSON gets the defaults. An unknown theme is not an error here -- it gets the defaults too, the same way the Python surface did; [Overlay] and [CSS] are what refuse a name the registry does not carry.

#Overlay

func Overlay(name string) (string, error)

Overlay returns the theme's own CSS file, without any framework sheets under it. An unknown theme is an error naming the registry.

#CSS

func CSS(name string) (string, error)

CSS returns the stylesheet for the named theme.

For a framework theme this is the composition: the framework's sheets followed by selfdoc's overlay. The whole composition sits below the critical-CSS marker, because the framework's @font-face rules are written relative to the stylesheet's own location and inlining them into a page at arbitrary depth would aim them at nothing.

#CSSRel

func CSSRel(name string) (string, error)

CSSRel returns where the named theme's stylesheet is written, from a site root.

#Asset.Bytes

func (a Asset) Bytes() ([]byte, error)

Bytes reads the asset's content.