Brand & appearance

Your academy should look like it belongs next to your docs. Admin → Brand is where you set how it looks: your logos, one brand color, your type, your corners, whether the academy is light, dark, or follows each reader's device, and the links in its header and footer. A live preview sits beside the form, so you see the result before anyone else does.

You never have to write CSS. You give the academy a few inputs, and it works out every shade from them, readable in light and dark mode. When you want more, Custom CSS (its own page, behind the card at the foot of Brand) takes a stylesheet of your own, written against a published reference — see Custom CSS.

Match my docs

The fastest start: paste your docs address (docs.yourcompany.com) into Match my docs and press Import. The form fills in with the brand your docs already wear:

Your docs run on	What comes across
Mintlify	Brand color, a dark-mode color when your docs use a different one, dark-mode background, both logos, favicon (as the mark), fonts, default appearance and whether readers may switch it
Docusaurus	Primary color for light and dark, dark-mode background, both navbar logos, touch icon or favicon, fonts, corner radius
Starlight	Accent color for light and dark, dark-mode background, both site-title logos, touch icon or favicon, fonts
Fern	Accent color for light and dark, dark-mode background, both logos, touch icon or favicon
Anything else	The page's theme color (or, failing that, your logo's own color, then a common --primary-style CSS variable), a dark-mode color when it declares one, light and dark logos in its header, its touch icon or favicon

A few notes on how the import works:

• It reads what your docs publish: Mintlify inlines its docs.json in every page, and Docusaurus, Starlight and Fern set CSS variables with known names. None of this is a documented API, so the import is best-effort, and whatever it finds is only a starting point for the form.
• Mintlify has three colors: one for light-mode links, one for dark-mode links, and one for buttons. The academy uses the first as your brand. If it has no hue (black text with yellow buttons, say), the button color becomes the brand instead. The dark-mode link color comes across only when it's a different color, like a neon beside a dark teal; a lighter shade of your brand is left out, because the academy already makes dark-mode links about that light and keeps dark-mode buttons in your brand color. The summary names the shade it used.
• A dark-mode background comes across only when it visibly differs from the one the academy would build anyway. A navy or near-black page does; the platforms' default greys don't. A dim grey page that's too light for every shade of a dark page is left out, and the summary says so.
• An import that finds a brand color replaces the whole color set: a dark-mode color or background it doesn't bring is cleared, not kept from before.
• Logos are read, not just linked: the import looks at what each one is drawn in. A logo with white lettering is drawn for dark backgrounds, so it goes in Logo for dark pages — a lone white wordmark never lands where it would vanish on a light page; light pages then show your mark beside the academy name until you add a light-mode logo. A logo pair your docs label the wrong way round is swapped.
• When your docs set no brand color of their own (or only a favicon generator's leftover default, like the Safari pinned-tab #5bbad5, which never counts), the brand comes from your logo's main color, and the summary says so.
• A font comes across only when it's on the academy's font list (below). If your docs use one that isn't, the summary names it so you can pick the closest match.
• Logos are linked, not copied: the academy shows the image from the address your docs use. If that address changes, update it here.

Logo

• Logo for light pages: a wide logo with your name in it. It replaces the academy name in the header, and appears on certificates and the sign-in pages. Leave it empty to show the mark beside the academy name instead.
• Logo for dark pages (optional): a version that reads on a dark page — white lettering goes here. Without one, dark pages show the light logo, so check the dark preview. Set alone, it shows on dark pages only, and light pages show the mark beside the academy name.
• Mark: a square icon. It's the browser-tab icon and the image in your certificates' Open Badges data. When there's no logo, it also sits beside the academy name in the header, on certificates and on the sign-in pages.

All three are links to images on your site or CDN (https:// only). Each field shows a thumbnail, so a broken link is obvious straight away.

Color

Pick one brand color. The academy builds everything else from it:

• Buttons and progress bars use your exact color. The only exception is a color that would disappear into the page (a very dark brand on a dark page); then the academy shifts it just enough to stay visible.
• Links use your color's hue at a lightness that reads as text. A yellow or neon brand gets dark-gold or olive links in light mode.
• Button labels are white or dark ink, whichever reads better on your color.
• Greys carry a whisper of your hue, so no two academies share the same grey. Choose Pure grey if you'd rather not.

If your brand only works on dark pages (a neon green, say), tick Use a different color in dark mode and give that color separately.

If your docs' dark mode has a background color of its own, like a deep navy, tick Use your own dark-mode background and give it. Dark pages then sit on exactly that color, and cards, lines and greys are built from it; text stays as readable as on the default dark page. A background that's too dark, too light or too vivid for every shade to hold is adjusted, and the preview notes say where it landed. The Greys choice then applies to light mode only.

Success and error colors never change: green means passed and red means failed in every academy.

Appearance

• Follow the system (the default): each reader gets light or dark, whichever their device uses.
• Always light or Always dark: the academy stays in one mode.
• Let learners switch between light and dark: adds a switch to the header (System, Light, Dark). The browser remembers each learner's pick, and there's no flash of the wrong mode on the next visit. Turn it off to keep everyone on the appearance above.

Printed pages (certificates, the training history) always print light — dark ink on white, whatever the screen shows.

The admin keeps Mastria's own look in every academy, so states read the same everywhere; your brand shows in its previews. Staff get the header switch there whatever you pick above, and choose light or dark for themselves.

Type

Pick a heading font, a body text font and a code font from a curated list:

• Text and headings: Mona Sans (the default), Inter, Geist, IBM Plex Sans, Source Sans 3, Roboto, Open Sans, Public Sans, DM Sans, Figtree, Manrope, Work Sans, Plus Jakarta Sans, Hanken Grotesk, Space Grotesk, Instrument Sans, Archivo, Albert Sans.
• Code: JetBrains Mono (the default), Fira Code, Source Code Pro, Geist Mono, IBM Plex Mono, Roboto Mono, Red Hat Mono.

The code font applies to lesson code blocks and to the lab editor. Every font on the list is served by the academy itself (no request to Google), and a reader's browser fetches a font file only when a page uses it.

Corners

Soft (the default), Sharp or Round: how rounded cards, buttons and fields are across the academy. Pills and avatars stay round.

Header and footer

• Header links: up to five links beside your logo — back to your product, your docs, your community. Each is a label (up to 30 characters) and an address: a full https:// link, or a path on the academy such as /courses (All courses), /paths (All learning paths), /catalogs (All catalogs), /paths/analytics-engineer or /catalogs/getting-started, with an optional icon from a short list (book, graduation cap, route, award, flask, rocket, compass and so on — the outline icons a product academy's "Modules / Learning paths / Certifications / Resources" row wears). On phones they fold into a menu button so the header never scrolls sideways. They don't show in the admin.
• Header layout: After the logo (the default) or In the middle of the bar — logo left, links centered in the room between the logo and the search and account controls, the way most product academies lay out their header. Phones keep the menu button beside the logo.
• Footer text: one plain-text line, such as "© Acme, Inc.".
• Footer links: up to six — terms, privacy, support. Labels and addresses only; icons are a header thing.
• Show "Powered by Mastria": on by default. Turn it off and the footer carries only your own text and links; with nothing of your own either, there is no footer.

A row left blank is ignored; a row with a label but no address (or the other way round) is named in the error line, so nothing half-typed goes live. External addresses open in the same tab — a header link is navigation, not an aside.

Cards

Course cards draw one of two ways wherever a course card is shown (the home and catalog pages; search results keep their own row layout):

• With a cover (the default): the course image above the title, or — when the course has none — a cover the academy generates from the course's own lab code or lesson titles, on your brand tint.
• Compact: no cover. The course image, when there is one, sits beside the title as a small square mark; otherwise a book mark does. Title, description and facts follow as before. This is the shape of a "modules" row on a product academy, where every card carries the product's icon rather than a picture.

Learning-path cards and the featured course keep their images either way — the featured band is its picture.

Preview and Save

The preview shows your academy as learners will see it, drawn from the form's current values: the header with your links, a course hero, a course card, a lab bench, your footer, the certificate and the sign-in email. It shows light above dark, or just one if you've locked the appearance.

One Save applies the whole page, and learners see the new look on their next page. Until you save:

• the bar at the bottom says there are unsaved changes, and Discard changes puts back what's saved;
• leaving the page through the admin asks you to save or discard first.

Where your brand shows

• every learner page: the header, cards, lessons, labs, certificates;
• the sign-in pages and the sign-in email: it's sent in your academy's name ("Sign in to Acme Academy", from "Acme Academy"), with your color on its button — and every other email a learner gets (certificates, recovery-email notices) comes from your academy's name too;
• link previews (the generated course and certificate images use your colors);
• the browser tab (your mark).

The admin itself keeps Mastria's own look, so buttons and status colors read the same in every academy. Your brand appears there only in previews: on this page, in course settings, and in the lesson preview.

Beyond the form

• Custom CSS. When the form isn't enough, Custom CSS takes a stylesheet of your own. Every learning platform that offers a CSS box ends up disclaiming it, because redesigns break it; ours is written against a published reference of tokens, landmarks and classes that a test in our build keeps stable, so what you write keeps working. It has a draft, a preview only you see, a publish, and a history.
• Your own rows on the home. Banner, Cards and HTML-block rows on the composed home carry content you write yourself, with stable hooks for your stylesheet — see Home & catalogs.
• Per-component colors or gradients stay out of the form on purpose: one color (plus an optional dark-mode color and background), derived consistently, is what keeps light, dark, yellow and neon brands readable. A second button color or an always-dark navbar is a few lines of custom CSS, where you own the readability.
• Your own font goes the same way: an @font-face in custom CSS pointing at a file on your CDN, and a type token set to it. The form's list covers what developer-tool docs use; if your brand font isn't on it, tell us.

What stays out, on purpose

• JavaScript. A stylesheet can't read a learner's session or change what a page records; a script could. HTML blocks on the home are allowed but cleaned on save (no scripts, event handlers, frames or forms), so every academy's labs, progress and certificates stay trustworthy. Integrations go through webhooks and the API — see Integrations & exports.