Getting Started#

Add MaterialDocs to your docs environment#

MaterialDocs belongs in docs/Project.toml, alongside Documenter — not in your package's own dependencies. It is only needed when building documentation.

using Pkg
Pkg.activate("docs")
Pkg.add("MaterialDocs")

Your docs/Project.toml should end up looking like this:

[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
MaterialDocs = "10bdffc8-969c-4dd4-83f3-742518eccd6b"
MyPackage = "..."

[sources]
MyPackage = {path = ".."}

[compat]
Documenter = "1"
MaterialDocs = "0.2"

Switch the format#

In docs/make.jl, swap Documenter.HTML for Material3. Any keywords you already pass to Documenter.HTML carry over unchanged — see Configuration:

using Documenter, MaterialDocs, MyPackage

makedocs(
    sitename = "MyPackage.jl",
    modules  = [MyPackage],
    format   = Material3(),
    pages = [
        "Home" => "index.md",
        "API"  => "api.md",
    ],
)

deploydocs(repo = "github.com/you/MyPackage.jl")

Build it from the root of your package:

julia --project=docs docs/make.jl

The result lands in docs/build. Open docs/build/index.html directly, or use the Theme Editor, which rebuilds and serves it for you.

format = Material3(prettyurls = get(ENV, "CI", nothing) == "true")

Pick a theme#

Twelve themes ship built in. Pass one by name:

format = Material3(theme = :ocean_depth)

See Theming for the full list, and for building your own from a seed color.

Add a dark mode toggle#

By default the site follows the reader's system preference. To offer an explicit toggle in the navbar:

format = Material3(dark_mode = :toggle)

Deploying#

MaterialDocs does not change how deployment works — keep using deploydocs:

deploydocs(
    repo = "github.com/you/MyPackage.jl",
    devbranch = "main",
)

Once deploydocs has published your docs, the navbar version selector appears automatically. It reads the versions.js and siteinfo.js files that deploydocs writes, so there is nothing extra to configure. On local builds those files do not exist and the selector stays hidden.