Documentation
¶
Overview ¶
Package theme resolves and loads HTML theme templates. Lookup order is project-local ./themes/<name>.html first, then the user config directory, then a small set of themes compiled into the binary.
Resolution never hard-fails: an empty name yields the default theme, and a name that can't be found or won't parse falls back to the default theme paired with a non-fatal diagnostic error so callers can warn the user while still rendering something presentable.
Index ¶
Constants ¶
const ( // DefaultName is the theme used when a document doesn't name one: a // styled, dependable allrounder built into the binary. "system" reads as // a special keyword rather than a real on-disk theme. DefaultName = "system" // NoneName is the bare passthrough theme — the rendered body with no // styling at all. Opt in with `theme: none` when you want zero opinions. NoneName = "none" )
Variables ¶
This section is empty.
Functions ¶
func SearchDirs ¶ added in v0.1.1
SearchDirs returns the directories searched for theme files, in order: the project-local <projectDir>/themes first, then the user themes dir (~/.config/mdoc/themes; see internal/paths).
Types ¶
type Fallback ¶ added in v0.1.1
type Fallback struct {
Requested string // theme name the document asked for
Used string // built-in theme used instead (DefaultName)
Reason string // terse reason, e.g. "not found" or "failed to parse"
Detail string // full human message, including searched locations
}
Fallback is the non-fatal diagnostic Resolve returns when it had to use the built-in default theme instead of the requested one. It implements error, so callers that only print err.Error() keep working (they get the full Detail); callers that want a terse, structured summary can type-assert and read the fields or call Short.
type Theme ¶
Theme is a parsed theme template ready to be executed by internal/render.
func Default ¶ added in v0.1.1
func Default() *Theme
Default returns the built-in default theme. Always available, never fails.
func Resolve ¶
Resolve finds a theme by name. It ALWAYS returns a usable, non-nil theme. A project-local or user theme file takes precedence over a built-in of the same name, so the built-in keywords ("system", "none") double as overridable starting points — including the default: an empty name is treated as the default theme name, so dropping a themes/system.html customizes what unstyled-by-frontmatter documents get. A name that can't be found anywhere, or a theme file that fails to parse, falls back to the built-in default.
The returned error is a non-fatal diagnostic, not a failure: callers should render with the returned theme and surface the error as a warning rather than abort. It is nil when the requested theme loaded cleanly (or resolved to a built-in, including when no theme was named at all).
Source Files