/cecil-theme

name: cecil-theme
description: Create, structure and package themes for Cecil (visual themes and component themes), following the conventions of the official Cecilapp/theme-* repositories.
license: EUPL-1.2

Cecil Theme Builder

You are an expert Cecil theme developer. You create reusable themes for [Cecil](https://cecil.app): full **visual themes** (layouts, styles, assets) and small **component themes** (a feature plugged into any site or theme), packaged for Composer like the official [Cecilapp themes](https://github.com/orgs/Cecilapp/repositories?q=theme).

For general Cecil usage (content, configuration, CLI), see the `cecil` skill.

When to Use This Skill

Use this skill when:

• Creating a new Cecil theme from scratch, or turning a site's `layouts/` into a reusable theme
• Creating a component theme (search, PWA, dark mode toggle, icons, redirects, headers, analytics, etc.)
• Installing or integrating an official component theme (e.g. `flexsearch`, `pwa`, `darkmodetoggle`) into a site or a visual theme; ask the user first (see "Ask the user before installing")
• Adding theme options, translations or assets to a theme
• Packaging and publishing a theme with Composer (`cecil/theme-<name>`)
• Debugging theme resolution (layouts, assets, config or translations not picked up)

How Cecil Loads Themes

A theme is **a website without pages**, stored in `themes/<name>/` and enabled in the site configuration:

theme: hyde
# or, for several themes (the first one overrides the others)
theme:
  - pwa
  - hyde

Resolution rules (from `src/`):

| Resource | Lookup order | |----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | Layouts | `layouts/` → `themes/<theme>/layouts/` (in `theme` list order) → Cecil internal `resources/layouts/` | | Assets | `assets/` → `themes/<theme>/assets/` → `static/` → `themes/<theme>/static/` (Sass import paths also include the theme's dirs) | | Static files | Themes' `static/` are copied first (reverse order), then site `static/`, so the site wins | | Translations | Cecil internal → `themes/<theme>/translations/` (in `theme` list order, so the **last** theme wins between themes) → site `translations/` (site wins) | | Data files | Site `data/` and each `themes/<theme>/data/` are loaded into `site.data` | | Configuration | `themes/<theme>/config.yml` overrides Cecil defaults (including default pages, generators and output formats), site config always wins (first theme wins between themes) |

Consequences:

• The config file **must** be named `config.yml` (not `config.yaml`); it's the only one loaded.
• A theme is considered installed when `themes/<name>/layouts/` or `themes/<name>/config.yml` exists; otherwise the build fails with `Theme "<name>" not found. Did you forgot to install it?`.
• Any site file with the same relative path overrides the theme file (layout, partial, asset, translation key, static file).
• Theme dependencies are **not** resolved transitively: a `theme:` key inside a theme's `config.yml` is ignored as soon as the site defines `theme`. Document the full list the user must declare (e.g. `theme: [links, fontawesome]`).

Theme Structure

Visual theme

theme-<name>/
├─ .editorconfig
├─ .gitattributes          # * text=auto
├─ .gitignore              # vendor/
├─ composer.json
├─ config.yml              # default config + namespaced theme options
├─ theme.yml               # optional metadata
├─ LICENSE
├─ README.md
├─ docs/
│  └─ screenshot.png
├─ assets/                 # processed by asset(): css/, sass/, js/, images
├─ static/                 # copied as-is: favicon.ico, fonts/
├─ data/                   # optional data files (site.data.*)
├─ layouts/
│  ├─ _default/
│  │  ├─ page.html.twig    # base layout (defines blocks)
│  │  ├─ list.html.twig    # sections, homepage fallback, terms
│  │  ├─ home.html.twig    # optional
│  │  ├─ term.html.twig    # optional
│  │  └─ vocabulary.html.twig
│  ├─ <section>/           # optional per-section layouts (e.g. blog/page.html.twig)
│  ├─ partials/            # header, footer, nav, pagination, post-item...
│  │  └─ notes/            # optional Markdown notes templates (`:::<type>` → <type>.html.twig)
│  └─ macros/              # optional reusable macros
└─ translations/
   └─ messages.fr.yml

Put layouts under `_default/`: this way a site can still provide its own top-level `page.html.twig` or `list.html.twig`, which take priority in the lookup.

Component theme

A component theme only ships what it needs, for example (structure of `theme-flexsearch`):

theme-<name>/
├─ .github/workflows/demo.yml     # builds demo/ and deploys it to GitHub Pages
├─ .gitattributes                 # export-ignore for .*, /demo, /docs
├─ composer.json
├─ config.yml                     # new virtual pages, output formats, options
├─ theme.yml
├─ README.md
├─ assets/<name>/                 # namespaced assets (e.g. flexsearch/flexsearch.css)
├─ demo/                          # demo website using the theme
│  ├─ config.yml
│  ├─ layouts/_default/page.html.twig
│  ├─ pages/
│  └─ link.php                    # links the repository as demo/themes/<name>
├─ docs/screenshot.png
├─ layouts/
│  ├─ _default/<layout>.<format>.twig
│  ├─ partials/<name>.html.twig   # snippet to include in <head> or <body>
│  ├─ partials/<name>/*.html.twig # optional sub-partials (e.g. trigger + dialog)
│  └─ macros/<name>.twig          # macros to import
└─ translations/messages.f