API Reference#

Material3 <: Documenter.Writer

A Documenter.jl writer that generates Material Design 3 documentation sites.

Material3 accepts every keyword Documenter.HTML does, with the same meaning and defaults, so switching writers is a rename: format = Documenter.HTML(...) becomes format = Material3(...). Those keywords are validated by constructing a Documenter.HTML, available as the html field. prerender, node and highlightjs are accepted but have no effect.

MaterialDocs keywords

• theme = :default: Built-in theme name (Symbol) or a ThemeConfig. When :default, automatically loads docs/.materialdocs.toml if present.

• dark_mode = :auto: Dark mode behavior. One of:

  • :auto — follows prefers-color-scheme

  • :light — always light

  • :dark — always dark

  • :toggle — adds a light/dark toggle button

• toc_depth = 3: Right-rail table-of-contents heading depth (2–4).

• search = true: Enable the search bar.

• versions = true: Show a version selector when deploydocs has generated versions.js / siteinfo.js. Hidden automatically on non-deployed builds.

• logo = nothing: Path to a logo image (relative to docs/src). When nothing, assets/logo.{svg,png,webp,gif,jpg,jpeg} is used if present, as in Documenter.

• favicon = nothing: Path to a favicon (relative to docs/src). An .ico in assets works too, as in Documenter.

repolink additionally accepts :auto, the same as leaving it unset.

Examples

# Use a built-in theme
format = Material3(theme = :ocean_depth)

# Use a custom theme
format = Material3(theme = ThemeConfig(seed = "#E65100", display_font = "Space Grotesk"))

# Documenter.HTML options carry over unchanged
format = Material3(
    theme = :midnight,
    dark_mode = :toggle,
    canonical = "https://you.github.io/MyPackage.jl/stable",
    assets = ["assets/extra.css"],
    footer = "Made with ❤️ and Julia",
)

ThemeConfig

Configuration for a MaterialDocs theme. Controls colors (via HCT seed), typography (via Google Fonts names), shape, and per-role color overrides.

Fields

• name::String: Human-readable theme name.

• seed::String: Primary seed hex color (e.g. "#6750A4").

• secondary_seed::Union{String,Nothing}: Override secondary palette seed.

• tertiary_seed::Union{String,Nothing}: Override tertiary palette seed.

• display_font::String: Google Fonts name for headings.

• body_font::String: Google Fonts name for body text.

• code_font::String: Google Fonts name for code blocks.

• corner_radius::Symbol: :sharp, :default, :rounded, or :pill.

• custom_colors::Dict{String,String}: Override individual MD3 color roles.

Examples

theme = ThemeConfig(seed = "#2E7D32", display_font = "Literata")

resolve_theme(theme) → ThemeConfig

Resolve a theme argument to a ThemeConfig. Accepts:

• A ThemeConfig (returned as-is)

• A Symbol naming a built-in theme (e.g. :default, :ocean_depth)

Throws ArgumentError if the symbol is not a known built-in theme.

BUILTIN_THEMES :: Dict{Symbol,ThemeConfig}

The twelve preset themes, keyed by name. Pass a key to Material3 or resolve_theme rather than indexing this directly:

format = Material3(theme = :ocean_depth)

Available keys: :default, :ocean_depth, :solar_flare, :midnight, :forest, :arctic, :rose_garden, :amber_workshop, :lavender, :sandstone, :neon_lab, :slate.

load_theme(path::String) → ThemeConfig

Load a theme from a .materialdocs.toml file. Returns a ThemeConfig with all fields populated (missing fields use defaults).

Throws ArgumentError if the file cannot be parsed or contains invalid values.

save_theme(config::ThemeConfig, path::String)

Write a ThemeConfig to a .materialdocs.toml file. Overwrites any existing file at path. The output is a clean, human-readable TOML file.

find_theme_toml(docs_dir::String) → Union{String, Nothing}

Search for a .materialdocs.toml file in the given directory. Returns the absolute path if found, or nothing.

editor(; build="docs/build", port=0, host=127.0.0.1, theme=resolve_theme(:default), make="docs/make.jl")

Launch the MaterialDocs theme editor — a local server that serves your actual built documentation with a floating theme editor panel injected.

Workflow

1. Build your docs: julia --project=docs docs/make.jl

2. Launch the editor: MaterialDocs.editor(build="docs/build")

3. Tweak colors, fonts, and shape in the panel — changes apply live

4. Click Copy TOML to export your configuration

The editor modifies CSS custom properties on :root, which instantly re-themes every component since all styles use var(--md-sys-*) tokens.

Keywords

• build: path to the built docs directory (default "docs/build")

• port: server port; 0 picks an available port automatically

• host: interface to listen on (default loopback, 127.0.0.1, so the preview is reachable only from this machine). Pass Sockets.IPv4(0) to expose it on your network — for example to check a build on a phone

• theme: initial ThemeConfig for the editor panel defaults

Example

using MaterialDocs

# After running makedocs:
MaterialDocs.editor()

# Or with a specific build dir and theme:
MaterialDocs.editor(build="docs/build", theme=resolve_theme(:ocean_depth))

Press Ctrl+C in the REPL to stop the server.