Documentation
¶
Overview ¶
Package theme resolves and loads HTML theme templates. A theme value is read one of two ways:
- A bare key (e.g. `thesis`) names a theme in the user config directory, ~/.config/mdoc/themes/<key>.html, or one of the themes compiled into the binary ("system", "none"). Bare keys are NOT searched for next to the document — that lookup is reserved for explicit paths, so it is always unambiguous which theme a key refers to.
- A scoped key (e.g. `kilohertz::legal::contract`) is a bare key in a subdirectory of the themes dir: the "::" segments map to path segments, so this resolves ~/.config/mdoc/themes/kilohertz/legal/contract.html. It lets a large theme library use folders without long flat names.
- A path (anything with a "/" separator, a leading "." or "~", an absolute path, or a file extension) names a theme file directly. A relative path resolves from the document's directory; an absolute or ~-prefixed path from the filesystem root or the user's home.
The key/scope/path distinction is the shared rule in paths.Classify, so themes and `:::include` references resolve identically.
Resolution never hard-fails: an empty value yields the default theme, and a key or path 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
func SearchDirs() []string
SearchDirs returns the directories watched for bare-key theme files: the user themes dir (~/.config/mdoc/themes; see internal/paths). The live-preview watcher uses it so a global theme created or changed mid-session is noticed; path-valued themes are watched separately via their resolved file path.
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. It ALWAYS returns a usable, non-nil theme. The value is either a bare key, looked up in the user themes dir (~/.config/mdoc/themes) and then the built-ins, or a path, resolved relative to docDir (see isPath/resolvePath). An empty value is treated as the default theme key. A user theme file takes precedence over a built-in of the same key, so the built-in keywords ("system", "none") double as overridable starting points — including the default: dropping a ~/.config/mdoc/themes/system.html customizes what unstyled-by-frontmatter documents get. Anything that can't be found, 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