Skip Navigation
Type MethodMethod

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

themeString

The theme to resolve (theme name, settings file or theme directory).

includeDarkMode

Whether to include dark mode styles.

customCSS

Optional custom CSS to append after the theme’s stylesheets.

warningHandler

Receives warnings about custom theme files.

Return Value

A theme configuration for the resolved theme.

Mentioned in

Discussion

The string is resolved as follows:

  1. If themeString is nil, the default theme is used.

  2. If the string is the path of an existing directory, it is read as a theme directory: a theme-settings.json file plus optional stylesheets (*.css, applied in file name order; files ending in .dark.css only when dark mode styles are enabled).

  3. If the string is the path of an existing file, it is read as a theme-settings.json file.

  4. 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 as classic), that theme is used.

  5. Otherwise, an error is thrown.

Custom theme files are validated like the built-in themes: unknown keys and feature switches are reported to warningHandler.

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")