[en] Start from Paligo Base

[en] Paligo Base is a complete theme, written to be changed. Download it, as described in [en] 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.

[en] Where things are

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

[en] Change colors, fonts and sizes

[en] 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:

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

Anmerkung

[en] 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.

[en] Light and dark mode

[en] 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.

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

[en] Change the page structure

[en] 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:

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

[en] 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.

[en] Style your content

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

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

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

[en] Right-to-left languages

[en] 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.

[en] Keep it working with Paligo

[en] Keep the site-search__… class names if you change the search box. See [en] Search in a theme.
[en] 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.
[en] Check the theme in light and dark mode, and on a topic page, the portal page and the search page.