blog.json and CSS for everything else.
blog.json
Colors
Colors are hex values with 3 or 6 digits, like
#0D9373.
Light and dark mode
appearance.default is "system" (follows the reader’s device), "light" or "dark". Readers pick light, dark or system with the switch in the footer, and the site remembers their choice. "strict": true hides the toggle and always uses the default, and the short form "appearance": "dark" sets only the default, so readers can still switch.
The site saves the choice in localStorage under notra-theme, as light, dark or system. When the site runs under a path of your website, like acme.com/blog, set storageKey to the key your main site uses so both share one choice, for example "theme" for a Next.js site with next-themes:
blog.json
., _ and -, up to 64 characters. This only works when your main site stores the same three values and serves the blog from the same domain, since a subdomain like blog.acme.com has its own storage.
Fonts
fonts.family selects a Google Font by name, while heading and body set a different font for each. Notra downloads the fonts and their licenses during the build and serves them from your site, so visitors don’t make requests to Google. If a download fails, the build reports a warning and the site uses system fonts:
blog.json
public/ and point source at it:
blog.json
weight is a number from 100 to 900: heading.weight sets how bold titles and headings are (500 by default), and weight or body.weight sets the body text. Pick a weight the font has, because the browser fakes bold for a font that only comes in 400, like Instrument Serif. format is woff2 (default) or woff, while code always uses the system’s monospace font.
Several files of one font
A font often comes as one file per weight, plus italics. List the other files infaces, which works on fonts, heading and body:
blog.json
source, plus an optional weight, style (normal or italic) and format, which defaults to the font’s format. For a variable font, give its range, like "weight": "100 900", and use weight on the font itself for the weight your text uses. A face without a weight covers every weight. With faces, source on the font itself is optional, and a font with faces or source is never downloaded from Google Fonts.
Loading
Notra preloads thewoff2 file your body text and headings use when it’s in public/, so text appears in your font sooner. While a font loads, the browser shows Arial resized to take the same space as your font, so text keeps its size and line breaks when your font arrives. Notra measures your font files during the build to set this up, for your own files and downloaded Google Fonts. If a file can’t be measured, the build warns and text shows in the default fallback font while yours loads.
Background
Width
layout.width sets the widest content column in rem, from 40 to 120, or "full", and the default is 72. Set it to the width of your landing page so the blog lines up with it. Index pages, posts and the reading column all scale with it, and with "full" the reading column keeps its default width.
Code blocks
styling.codeblocks picks the syntax theme. See Code.
Smart quotes
Notra turns straight quotes and apostrophes into typographic ones as it builds your posts, so"Hello" becomes “Hello” and it's becomes it’s. -- becomes an en dash and ... an ellipsis. Code stays as written.
If you move posts from another site and want the text to look exactly as before, turn it off:
blog.json
Your own CSS
Every.css file in the site loads on every page after the theme, so it can override anything, whether it’s style.css, styles/brand.css or buttons.css next to a component.
style.css
--background, --foreground, --muted, --muted-foreground, --border, --accent, --card, --success, --warning, --info and --destructive. --accent is your brand color for the current mode, while --primary always holds colors.primary. Use html.dark to style dark mode only.
Tailwind classes also work in your MDX, header, footer and components.
To use a font or image from public/ in your CSS, reference it from the root of the site, the same way as in posts. Notra adds the section’s path, so /fonts/acme-sans.woff2 loads from /blog/fonts/acme-sans.woff2 on the blog and from /changelog/fonts/acme-sans.woff2 on the changelog, both in notra dev and on your published site:
style.css
@scope (.header), its rules apply to elements inside .header but not to .header itself, which is how @scope works in every browser. Style the root with :scope { ... } inside the block.
Styling hooks
These IDs and class names stay stable, so your CSS keeps working when the theme updates.
The navbar IDs only exist in the built-in header and
#footer only in the built-in footer, so with your own header.mdx, use your own class names.