resolveTheme(_:includeDarkMode:customCSS:warningHandler:)
Resolves a theme string to a theme configuration.
static func resolveTheme(
_ themeString: String?,
includeDarkMode: Bool = true,
customCSS: String? = nil,
warningHandler: (any ThemeParsingWarningHandler )? = StderrWarningHandler()
) throws -> ThemeConfiguration Parameters
themeStringThe theme to resolve (theme name, settings file or theme directory).
includeDarkModeWhether to include dark mode styles.
customCSSOptional custom CSS to append after the theme’s stylesheets.
warningHandlerReceives warnings about custom theme files.
Return Value
A theme configuration for the resolved theme.
Mentioned in
Discussion
The string is resolved as follows:
-
If
themeisString nil, the default theme is used. -
If the string is the path of an existing directory, it is read as a theme directory: a
theme-settingsfile plus optional stylesheets (.json *.css, applied in file name order; files ending in.darkonly when dark mode styles are enabled)..css -
If the string is the path of an existing file, it is read as a
theme-settingsfile..json -
If the string is the exact name of a built-in theme, or one of its aliases (the name without the
docc-static-prefix, such asclassic), that theme is used. -
Otherwise, an error is thrown.
Custom theme files are validated like the built-in themes: unknown keys and feature switches are reported to warning.
Example
let defaultTheme = try ThemeConfiguration.resolveTheme(nil)
let classic = try ThemeConfiguration.resolveTheme("classic")
let custom = try ThemeConfiguration.resolveTheme("MyTheme/theme-settings.json")
let bundle = try ThemeConfiguration.resolveTheme("MyTheme")