/cecil

name: cecil
description: Build and configure Cecil static sites, with focused guidance for content, templates, and site generation.
license: EUPL-1.2

Cecil Site Builder

You are an expert Cecil developer capable of creating and generating static websites with Cecil, a PHP-based static site generator powered by Symfony components and Twig.

When to Use This Skill

Use this skill when:

• Creating or scaffolding a new Cecil site
• Building and generating static websites with Cecil
• Configuring site settings, taxonomies, and content organization
• Creating or updating Twig templates and layouts
• Managing assets, including images and stylesheets
• Deploying Cecil-generated static sites
• Troubleshooting build issues or optimizing the performance of the generated site and build process
• Working with Cecil's plugin/extension system

Project Structure

Directory Layout

my-site/
├── cecil.yml  # Main configuration file (or config.yml)
├── pages/     # Markdown pages
├── layouts/   # Twig templates
├── assets/    # Processed files (CSS, JS, images)
├── static/    # Static files copied as-is
├── data/      # Data collections (YAML/JSON/...)
└── extensions/ # Custom PHP classes (generators, Twig extensions, post-processors)

Key Directories

• **pages/** - Markdown content files organized into sections
• **layouts/** - Twig templates and partials
• **assets/** - Files handled by Cecil (Sass compilation, minification, image handling)
• **static/** - Files copied to output without transformation
• **data/** - Data files exposed in templates via `site.data`
• **extensions/** - Custom PHP classes autoloaded by Cecil (file path must match the class namespace, e.g. `extensions/MyProject/Generator/CustomGenerator.php`)

Cecil Fundamentals

Architecture

Cecil follows a build pipeline:

Builder → Steps → Generators → Renderer → Output

• **Steps** (`Step/`): Sequential build phases, in this order
• Load: pages, data files and static files
• Pages Create / Convert: create pages collection, convert front matter and Markdown body
• Taxonomies Create: build vocabularies and terms
• Pages Generate: run generators (see below)
• Menus Create: build navigation structures
• StaticFiles Copy: copy static files
• Pages Render / Save: render with Twig and write output files
• Assets Save: save processed assets
• Optimize: HTML, CSS, JS and images

• **Generators** (`Generator/`): Page generators executed via priority queue
• Generators are ordered by numeric weight; lower numbers execute first (e.g., DefaultPages at weight 10 runs before Alias at weight 80).
• DefaultPages (10) → VirtualPages (20) → ExternalBody (30) → Section (40) → Taxonomy (50) → Homepage (60) → Pagination (70) → Alias (80) → Redirect (90)

• **Renderer** (`Renderer/`): Twig-based rendering with custom extensions
• **Output**: Built static site in `_site/` directory

Content Model

• **Pages**: Markdown files composed of front matter and body
• **Front matter**: Metadata surrounded by separators (`---`, `+++`, or `<!-- -->`)
• **Section**: Root folder in `pages/` (e.g. `pages/blog/post-1.md` -> section `blog`)
• **File-based routing**: Files under `pages/` define generated paths
• **Collections**: Pages, taxonomies, data and static files are exposed to templates

Nested Sections (Sub-sections)

A nested folder that explicitly contains an `index.md` file becomes a _sub-section_ of its parent _Section_. A nested folder **without** an `index.md` file is not a sub-section: its pages simply belong to the parent section.

pages/
└─ blog                 # Section "blog"
   ├─ index.md
   ├─ post-1.md         # Page in "blog"
   └─ 2024              # Sub-section (contains an "index.md")
      ├─ index.md
      └─ post-2.md      # Page in "blog" AND "blog/2024"

A sub-section:

• Is a full _Section_ (same `type`, variables, and [layout](../../docs/templates/1-lookup-rules.md) resolution) available at its own URL (e.g. `/blog/2024/`)
• Falls back to the templates of its parent sections (e.g. `blog/list.html.twig` for `blog/2024` if `blog/2024/list.html.twig` doesn't exist)
• Can be nested at any depth (e.g. `blog/2024/06/`)
• Lists its own pages; those pages also belong to each parent section
• Is **not** listed among the pages of its parent section

Sub-sections support the same front matter variables as any section (`sortby`, `pagination`, `cascade`, `circular`). Use `cascade` on a parent `index.md` to propagate variables down to sub-sections and their pages.

In templates, use `page.parent`, `page.ancestors`, `page.sections` and `page.toplevel` to build navigation, or include the ready-to-use `partials/breadcrumb.html.twig` partial.

Previous/next navigation (`page.prev` / `page.next`) follows the sections tree: the pages of a top level section and of all its sub-sections are chained depth-first, sorted with the section's `sortby`, each sub-section index page being followed by its own pages.

Configuration

Configuration is defined in `cecil.yml` or `config.yml` at project root:

• Core options are top-level keys such as `title`, `baseurl`, `description`, `taxonomies`, `menus`
• Dot notation in templates applies to `site` variable access (for example `site.title`)
• Defaults (including generators, default pages and output formats) are defined in `config/default.php`; priority is defaults < themes `config.yml` < site config < env vars (`CECIL_*`)
• Maps are merged key by key with the defaults; a boolean applied to a map toggles its `enabled` key (e.g. `cache: false`); in templates, check it with the `enabled` test (`{% if config.cache is enabled %}`)
• A list of values (`pages.ext`, `output.pagetypeformats.<type>`, `assets.images.responsive.widths`…) replaces the default list but is added to the theme list; a map of booleans adjusts the default or theme list instead (e.g. `homepage: {rss: true, atom: false}`)
• `output.formats` entries are merged by `nam