Start from Paligo Base

Paligo Base is a complete theme, written to be changed. Download it, as described in Download a theme, and change as much or as little as you want: its colors and fonts, its templates, or all of it. This topic describes how it is built, so that you know where to make a change.

Where things are

File	Contains
`templates/base.html.twig`	The page frame for every page: the header, the navigation sidebar and the footer. Read it first.
`templates/page.html.twig`	Topic pages: the breadcrumb trail, the content, the previous and next links, and the on-page table of contents.
`templates/portal.html.twig`	The portal page: the banner, the featured topics and the list of topics.
`templates/search.html.twig`	The search results page.
`templates/partials/`	The logo and site title, the portal banner, the search box and the light and dark mode button.
`assets/css/main.css`	All of the theme's styles. Its first section sets the colors, fonts and sizes.
`assets/css/theme.css`	Styles for the output of the `paligo_…()` components.
`assets/css/code-theme.css`	Code colors, used when the layout's Code colours is Theme colours.
`assets/js/`	Scripts for the navigation sidebar, the on-page table of contents, the light and dark mode button and the portal.
`i18n/en.json`	The theme's own texts, in English.
`README.md`	A short introduction to the theme.
`AGENTS.md`	Instructions for AI coding assistants. See Build a theme with an AI coding assistant.
`CLAUDE.md`	Points Claude Code to `AGENTS.md`.

Change colors, fonts and sizes

Most changes only need the CSS custom properties at the top of assets/css/main.css. Every color, font and size in the theme comes from them:

Property	Controls
`--paligo-primary`, `--paligo-primary-hover`	Links, buttons and highlights. The Accent color option sets these.
`--paligo-brand`, `--paligo-brand-end`	The two colors of the gradient on the built-in logo mark and the current navigation item.
`--paligo-bg`, `--paligo-surface`, `--paligo-surface-2`	The page background, and the background of the sidebar, code blocks and admonitions.
`--paligo-text`, `--paligo-muted`, `--paligo-faint`	Text colors, from strongest to faintest.
`--paligo-border`, `--paligo-border-strong`	Borders.
`--paligo-note`, `--paligo-tip`, `--paligo-important`, `--paligo-caution`, `--paligo-warning`, `--paligo-danger`	The color of each type of admonition.
`--paligo-font`, `--paligo-mono`	The text font and the code font.
`--paligo-font-size`, `--paligo-line-height`	The size and line spacing of text.
`--paligo-radius-sm`, `--paligo-radius`, `--paligo-radius-lg`	Rounded corners.
`--paligo-header-h`, `--paligo-sidebar-w`, `--paligo-toc-w`, `--paligo-shell-max`	The height of the header, the widths of the sidebar and the on-page table of contents, and the greatest width of the page.
`--paligo-code-keyword`, `--paligo-code-string`, `--paligo-code-comment` and the other `--paligo-code-…` properties	Code colors, when Code colours is Theme colours. They are in `code-theme.css`.

:root {
    --paligo-primary: #0b7a75;
    --paligo-primary-hover: #075955;
    --paligo-font: "Source Sans 3", system-ui, sans-serif;
}

Note

Paligo Base loads the Inter font from Google Fonts. To serve your own font instead, add it to assets/fonts/ as a WOFF2 file, declare it with @font-face, change --paligo-font, and remove the @import of Google Fonts at the top of main.css.

Light and dark mode

Paligo Base follows the reader's light or dark setting, and readers can switch with the button in the header. The dark colors are a second set of the same properties, in main.css under @media (prefers-color-scheme: dark) and :root[data-theme="dark"]. If you change a color, change it in both sets.

When a reader selects the button, the <html> element gets data-theme="light" or data-theme="dark", and the browser remembers the choice.

Change the page structure

base.html.twig is divided into Twig blocks, which the other templates replace where they need to. To change one part of every page, edit that block in base.html.twig:

Block	Contains
`chrome`	The header and the navigation sidebar together.
`nav_toggle`	The menu button for the sidebar on small screens.
`topbar_search`	The search box in the header.
`header_tools`	The language menu and the light and dark mode button.
`crumb`	The breadcrumb trail.
`sidebar`	The navigation sidebar.
`main`	The main area of the page.
`content`	The content inside the main area.
`title`	The page title in the browser tab.
`body_class`	Classes on the `<body>` element.

Keep {{ paligo.head }} and {{ paligo.foot }} in base.html.twig, and keep your stylesheets after {{ paligo.head }}, so that your styles take priority over Paligo's.

Style your content

Paligo writes the HTML for your content, and gives it these classes:

Content	Classes
Admonitions	`.admonition` with `.note`, `.tip`, `.important`, `.caution`, `.warning` or `.danger`, containing `.title` and `.body`
Figures	`.figure`, `.informalfigure` and `.caption`
Tables	`.informaltable` and `.table`
Code	`pre`, `code` and `.code-block`, with `.code-copy` for the copy button
Accordions	`details.accordion` and `.accordion-body`
Glossary terms	`a[data-glossary-def]`, and `.glossary-popover` for the popup
Interface names and keys	`.guilabel` and the other `.gui…` classes, and `.keycap`
Untranslated text in a draft	`.translation-missing` and `.translation-changed`

Paligo's own stylesheet styles these, and main.css styles them again. To change them, change the rules in main.css.

Right-to-left languages

Paligo Base sets dir="rtl" on pages in right-to-left languages, but its stylesheet isn't mirrored for them. If you publish in Arabic or Hebrew, check every page type and add the rules you need, such as for [dir="rtl"] .site-nav.

Keep it working with Paligo

Keep the site-search__… class names if you change the search box. See Search in a theme.
Keep an option's key in theme.json when you change the option. Layouts store their values by key, so renaming a key loses the value set for it on every layout.
Check the theme in light and dark mode, and on a topic page, the portal page and the search page.