Themes, Fonts and Code Themes

Three of a documentation set’s settings decide how it looks: a color theme, a font and a code theme. They are independent of each other and of the layout, they each have a built-in catalog and a default, and each one can instead carry a name of your own that you back with CSS in your site repository.

What each choice controls

Color theme drives the accent: body links, the active navigation item, buttons, borders and the tinting of the docs chrome. It does not change your typography.

Font is the typeface for the whole set — body, headings and navigation together.

Code theme is syntax highlighting inside code blocks, and nothing else. It does not affect inline code color elsewhere on the page.

All three live on the documentation set’s page type. On the page type panel in Settings → Page Types, Font and Code Theme sit under General Details while Theme sits under Configuration Overrides — an accident of how the panel is grouped rather than a difference in kind. The same three fields appear in Settings → General as your company-wide defaults; see Default Content Configuration for how those propagate.

The built-in catalogs

The layout is a fourth choice made in the same place and is documented at Documentation Layouts; its default is Alpha.

Two failures that do not look alike

A misspelled color theme and a misspelled code theme are the same mistake, and they produce completely different symptoms. This is the section worth remembering.

A color theme degrades quietly. Every component in the docs reads a --component-* variable, and each of those resolves through a chain — the docs theme first, then your site’s palette, then Leed’s defaults. An unresolved theme name simply falls out of that chain at the first rung, so the set renders in your site’s own colors. It looks correct, just un-branded. The tell is that nothing is wrong, only unaccented: links in the site’s default color, no themed active navigation item.

A code theme does not degrade at all. Code themes carry no variables and no fallback chain: each is a block of plain highlight.js class rules, and those rules also carry the code block’s own layout — the block display, the padding, the horizontal scroll. So an unresolved code theme name means code blocks lose their colors and their shape. Long lines stop scrolling and start overflowing. It is immediately obvious, which is the one good thing about it.

Same-shaped mistake, two symptoms, two fixes: for a color theme, check that the CSS defining it is in your repository; for a code theme, check the spelling against the table above before you look at anything else.

Naming your own theme

Instead of picking from a catalog, you can type a name of your own for the color theme, the code theme or the font. Choosing Custom… in any of those three fields swaps the dropdown for a text box.

What the CMS accepts

You type a bare name and Leed stores the prefixed class. The bare name must be lowercase letters and digits only — no dashes, no capitals, no underscores — and at most 32 characters.

leed      → color-theme-leed        accepted
leedai    → color-theme-leedai      accepted
leed-ai   →                         rejected: the bare name contains a dash
LeedAI    →                         rejected: the bare name contains capitals

The dash rule is the surprising one, because the stored value is full of dashes and so are all the built-ins. The rule applies only to the part you type.

A malformed name is refused on every plan, before your plan is even consulted:

400  Invalid colorTheme: a custom name must be lowercase letters and numbers
     only, at most 32 characters.

A well-formed new custom name below Starter gets an upgrade response instead — the same 402 shape every gated feature returns, naming customThemeNames. When a Feature Is Gated explains what that response means and what still works.

The gate applies only to a change

The check fires on introducing a custom name, never on carrying one. Keeping the name you already have, clearing it, or swapping one built-in for another all succeed on every plan — including after a downgrade. You are never locked out of your own settings, and opening the page type panel on a Free workspace that once had a custom theme does not fail.

Each of the three fields is checked on its own: a valid custom color theme in the same save does not vouch for a malformed font name.

A name is not a theme

Setting mybrand puts the class color-theme-mybrand on every page of the set and does nothing else. The CSS that gives the name meaning is a file in your site repository, and writing it is the other half of this feature — Custom Documentation Themes walks through one end to end, including which variables a theme is expected to set.

These pages are the worked example. Leed’s own documentation runs color-theme-leed and code-theme-leed, both authored as overrides in the site repository exactly the way a customer writes them, rather than shipped inside the product.

Extra syntax languages for code blocks

Code blocks highlight the languages highlight.js bundles by default. You can add more.

Add them in Settings → General, in the Custom Highlighter Syntax field. Two things then happen: the language becomes selectable in the page editor’s code-block language picker, and your site build looks for the matching highlight.js grammar in your site repository at src/static/js/hljs-<language>.js and loads it on documentation pages. If that file is not there, the build logs a warning and moves on — the language is configured but nothing highlights, so ship the grammar file with the setting.

Which languages highlight by default, and how a fenced block picks one, is on Code Blocks.

Fonts need three things to line up

A font applies only when three pieces agree: a --font-<name> design token, an @font-face declaration pointing at real files, and an entry in the builder’s font catalog so the files get installed. Leed ships all three for every family in the dropdown, and the build downloads the webfont files into your repository automatically the first time a font is used — so picking one from the list is genuinely one click.

The three pieces matter the moment you stop picking from the list. A name typed into the custom field is checked by nothing: if no token stands behind it, Tailwind emits no rule, the class is inert, and the page quietly keeps the typeface it already had. There is no error to notice. So whenever you type a font name rather than choosing one, confirm it applied by looking at a rendered page.

Installing a face Leed does not ship — your own brand font — is a repository job covered at Fonts and Webfonts.

Where the classes end up

The root element of every documentation page carries all four appearance classes together, in a fixed order: font, layout, color theme, code theme.

<html class="leed-documentation font-open-sans docs-layout-charlie color-theme-leed code-theme-leed">

That is the contract for anything you write yourself. A rule scoped to .color-theme-leed fires only for sets using that theme; a rule scoped to .leed-documentation fires on every documentation page and nowhere else on your site. Layout is the only one of the four stored without its prefix — the builder adds docs-layout- when it writes the class.