MaterialDocs.jl GitHub

MaterialDocs.jl#

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

Pass Material3() as your format and every page is rendered against a full MD3 token system — colors, typography, shape, elevation, and motion — generated at build time from a single seed color.

This site is built with MaterialDocs. Everything you see here is the output.

Installation#

using Pkg
Pkg.add("MaterialDocs")

Quick start#

In docs/make.jl, replace Documenter.HTML with Material3:

using Documenter, MaterialDocs, MyPackage

makedocs(
    sitename = "MyPackage.jl",
    modules  = [MyPackage],
    format   = Material3(theme = :ocean_depth, dark_mode = :toggle),
    pages    = ["Home" => "index.md"],
)

That is the whole integration. MaterialDocs registers itself through Documenter's FormatSelector, so makedocs dispatches to it automatically.

What you get#

  • A full palette from one color. MaterialDesignColors.jl turns a single seed into all 34 MD3 color roles, in light and dark. Every text-on-container pairing in the twelve built-in themes clears WCAG AA contrast. See Color Engine.

  • Twelve built-in themes, or your own via ThemeConfig. See Theming.

  • A live theme editor. editor serves your real documentation with a panel that re-themes it as you drag a color picker, then gives you the theme as TOML to save. See Theme Editor.

  • Light and dark modes, following the system preference or a toggle.

  • Everything Documenter renders. Docstrings, doctests, @example output (HTML, SVG, PNG, JPEG, GIF, WebP, LaTeX, Markdown), and math via KaTeX.

  • MD3 search. A search bar that expands into a docked search view on wide windows and a full-screen view on narrow ones.

  • Version selector and repository link in the navbar, wired to the metadata deploydocs already writes.

  • No Node.js. Pure Julia, producing a static site you can host anywhere.

How it fits together#

MaterialDocs replaces only Documenter's rendering stage. Everything upstream — parsing, cross-references, doctests, @docs blocks — is unchanged Documenter, so existing documentation works without edits.

Because every stylesheet references var(--md-sys-*) custom properties and never a literal color, changing the tokens re-themes the entire site. That is what makes the live editor possible.

Pages load their fonts from Google Fonts, and syntax highlighting and math typesetting (KaTeX, only on pages with math) from a CDN, so readers without network access see system fonts, unhighlighted code, and raw LaTeX.

Documenter features that need a renderer of their own — typically from extension packages such as DocumenterCitations — have their text kept but not their formatting, and the build logs a warning naming each such element type once.

Where to go next#