Project Manual
Contents

Create and Select Themes

Themes change the visual design without replacing generated HTML, responsive layout, accessibility behavior, or search JavaScript. The default ef-maris-dark theme matches the current dark desktop palette.

Select a theme#

Pass the theme name to Python:

python3 build.py --theme modus-operandi-tinted

Use the same name with Make:

make bundle THEME=modus-operandi-tinted
make offline-bundle THEME=modus-operandi-tinted
make example THEME=modus-operandi-tinted PORT=8080

Builder containers accept --theme modus-operandi-tinted. nginx images accept the build argument --build-arg THEME=modus-operandi-tinted.

Built-in themes#

Dark themes:

  • Ef Bio: ef-bio.
  • Ef Dream: ef-dream.
  • Ef Elea Dark: ef-elea-dark.
  • Ef Maris Dark: ef-maris-dark.
  • Ef Night: ef-night.
  • Ef Owl: ef-owl.
  • Ef Symbiosis: ef-symbiosis.
  • Modus Vivendi Tinted: modus-vivendi-tinted.
  • Terminal: terminal.

Light themes:

  • Ef Cyprus: ef-cyprus.
  • Ef Day: ef-day.
  • Modus Operandi Tinted: modus-operandi-tinted.
  • Paper: paper.

Add a theme#

Create a lowercase, hyphenated directory under themes/:

themes/
└── company/
    ├── theme.css
    └── mark.svg

The theme.css file is required. Other regular files and directories are optional. No registry or generator change is needed. Build the new theme with:

make bundle THEME=company

Use theme assets#

Reference files beside the stylesheet with relative CSS URLs:

.site-title::before {
  background-image: url("./mark.svg");
}

Do not use /assets/ paths in theme CSS. Relative paths work for root hosting, project prefixes, and extracted offline ZIPs.

Shared typography#

All built-in themes use the same self-hosted JetBrains Mono font for body text, headings, navigation, search, and code. Light and light italic provide 300-weight reading text. Regular, italic, bold, and bold italic remain bundled for explicit normal and strong text, so typography does not require an installed font or internet connection.

The font files are pinned to JetBrains Mono version 2.304, matching the Omarchy Manual assets. They are distributed under the SIL Open Font License 1.1 in assets/fonts/OFL.txt.

The shared Omarchy scale responds from 10px to 16px for site text and from 13px to 16px for documentation text, with a 1.4 reading line height. H1, H2, and H3 headings use 175%, 130%, and 110% of the documentation text size. TOC section labels keep their local uppercase hierarchy.

Theme authors and licenses#

The Ef and Modus adaptations use exact semantic colors from the desktop theme renderer. Ef Themes 2.2.0 is pinned at commit 5cdb7dd361ad3b5d7310f94375a832cd94c182d8 and was resolved with Modus Themes commit 75aa3fa79efd04ddf7980a1d3ec0cef6e4f4af90. The Modus Tinted themes use that Modus revision directly. It declares package version 5.3.0 but is newer than the 5.3.0 tag.

The upstream author and maintainer is Protesilaos <info@protesilaos.com>. Copyright is held by the Free Software Foundation, Inc. Ef and Modus theme adaptations are licensed under GPL-3.0-or-later; each theme includes a NOTICE, and the full license is in assets/licenses/. Simple Docs code plus the terminal and paper themes remain MIT licensed. JetBrains Mono remains under the SIL Open Font License 1.1.

The ports preserve desktop semantic colors exactly. Those roles are reused on different web surfaces, so some muted text and search combinations fall below a 4.5:1 contrast ratio. Do not infer upstream accessibility guarantees for these adaptations.

Keep behavior shared#

Core rules remain in assets/manual.css, and search remains in assets/manual.js. A theme should set design variables and add focused visual overrides in theme.css. It cannot replace the core JavaScript.

The generator rejects invalid theme names, missing stylesheets, symlinks, special files, unsafe filenames, and theme paths that overlap generated output.

Return to the generating sites overview, use a theme in a Python build, a container build, or with the Make helpers. To change the manual name, header mark, or favicon, continue to customize branding.