# Create a theme A theme is not a special file format. It is a **normal epresso project shaped for reuse**: the same `components/`, `layouts/`, `styles/`, `pages/` and `site.toml` you already write, plus two conventions — *everything visual is a component*, and *site-specific values come from configuration, not from the theme's own files*. Use [`themes/docs`](https://github.com/nikoshell/epresso/tree/main/themes/docs) as the reference implementation. ## 1. Start a project ```bash epresso init epresso-theme-mytheme cd epresso-theme-mytheme ``` Name the directory after the theme — a sibling repo named `epresso-theme-` is exactly what the theme registry looks for when developing locally (see step 5). ## 2. Adopt the theme conventions A reusable theme keeps to a shape that makes it predictable to override: ```tree epresso-theme-mytheme/ site.toml # defaults + a [theme] table for options layouts/ # page shells (Base.ep, Doc.ep) — expose components/ # every visual element, grouped by role ... styles/ global.css # design tokens (:root vars), resets, fonts pages/ index.ep # a starter page, or nothing at all content.config.py # only if the theme owns a collection (e.g. docs) README.md # what the theme provides and which options it reads ``` Rules of thumb: - **No hard-coded branding.** Names, URLs, menus and accents come from `site.toml` (`[site]`) or the theme's own `[theme]` table, never from a literal in a component. - **Global styles live in `styles/`.** Only truly document-wide things — tokens, fonts, resets. Everything component-specific goes in that component's scoped `

``` A component reads the same table — frontmatter runs with `site` in scope: ```epresso --- from pydantic import BaseModel class Props(BaseModel): title: str subtitle: str = "" ---

{% if props.subtitle %}

{% endif %} {{ content }}

``` ## 4. Test it like a project A theme is buildable on its own: ```bash epresso dev . # live reload epresso build . # → dist/ epresso check . # validate config + routes epresso fmt . # canonical .ep formatting ``` Create a scratch site that consumes the theme to check the parts a theme cannot exercise alone (navigation, missing options, empty collections): ```bash epresso new mytheme /tmp/consumer cd /tmp/consumer && epresso dev ``` ## 5. Make `epresso new` find it Register the theme in `src/epresso/themes.py`: ```python REGISTRY: dict[str, tuple[str, str]] = { # name -> (repo path or URL, default branch) "docs": ("/themes/docs", "main"), # ships in this repository "blog": ("...epresso-theme-blog", "main"), # sibling checkout / git URL "mytheme": ("https://github.com/you/epresso-theme-mytheme", "main"), } ``` The value may be an **in-repo path** (themes that ship with epresso, like `themes/docs`), a **local path** to a sibling checkout while developing, or a **published git URL**. Then: ```bash epresso new mytheme mysite ``` See [Start from a template](guides/themes/from-template.md) for the resolution order and the failure mode when a theme is unreachable. > **Note:** registering a theme currently means editing `themes.py`. Publishing a > theme as an installable package — so consumers add it with their package > manager instead — is designed but not implemented. It is covered by a *Coming > soon* tutorial, visible in local previews. ## 6. Document the theme Your theme's `README.md` is its contract. List: - the options it reads from `[theme]` (and their defaults), - the collections it expects, if any, - the components it exposes for pages to use, - anything a consumer must keep (e.g. a specific `[assets] css` entry). ## Next steps - [Start from a template](guides/themes/from-template.md) — what a consumer runs. - [Components](../basics/components.md) — props, slots, scoped CSS. - [Plugins](../guides/extending/plugins.md) — if the theme needs template globals or filters (ship a `plugins.py`, as `epresso-ui` does).

{{ props.title }}