// Build and configure Cecil static sites, with focused guidance for content, templates, and site generation.
Standard workflow to address pull request review comments in Cecil. Use when responding to review feedback, fixing requested changes, or preparing a clear reviewer reply with reproduction, fix, tests, and response.
Expert guidance for PHP 8+ development, prioritizing code quality (SOLID, PSR standards), security practices, and testing requirements
| name | cecil |
| description | Build and configure Cecil static sites, with focused guidance for content, templates, and site generation. |
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.
Use this skill when:
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/...)
site.dataCecil follows a build pipeline:
Builder → Steps → Generators → Renderer → Output
Steps (Step/): Sequential build phases
Generators (Generator/): Page generators executed via priority queue
Renderer (Renderer/): Twig-based rendering with custom extensions
Output: Built static site in _site/ directory
---, +++, or <!-- -->)pages/ (e.g. pages/blog/post-1.md -> section blog)pages/ define generated pathsConfiguration is defined in cecil.yml or config.yml at project root:
title, baseurl, description, taxonomies, menussite variable access (for example site.title)config/default.php and base pipeline in config/base.phpDownload Cecil using curl:
curl -LO https://cecil.app/cecil.phar
chmod +x cecil.phar
Verify the download:
php cecil.phar --version
Use the new:site command to scaffold a new website:
php cecil.phar new:site
Edit cecil.yml:
title: My Site
baseurl: https://example.com/
description: My awesome static site
taxonomies:
categories: category
tags: tag
Create a page with:
php cecil.phar new:page
Then edit the generated file in pages/:
---
title: My First Post
description: Welcome to my blog
date: 2024-05-14
tags: [Welcome, "First post"]
---
# My First Post
This is my first post content.
Create Twig templates in layouts/ (for example layouts/page.html.twig):
<!DOCTYPE html>
<html>
<head>
<title>{{ page.title }} - {{ site.title }}</title>
</head>
<body>
<header>
<h1>{{ site.title }}</h1>
</header>
<main>
{{ page.content }}
</main>
<footer>
<p>© {{ site.title }}</p>
</footer>
</body>
</html>
php cecil.phar build
Output is generated in _site/ directory.
| Command | Purpose |
|---|---|
php cecil.phar new:site | Create a new website |
php cecil.phar new:page | Create a new page |
php cecil.phar build | Build the static site |
php cecil.phar serve | Start local server with live reload |
php cecil.phar show:config | Display effective configuration |
php cecil.phar cache:clear | Clear all cache files |
php cecil.phar self-update | Update Cecil |
php cecil.phar clear | Remove generated files |
php cecil.phar util:templates:extract | Extract built-in templates into layouts |
Twig templates live in layouts/ and follow Cecil naming conventions.
Use this pattern:
layouts/(<section>/)<type>|<layout>.<format>(.<language>).twig
Examples:
layouts/page.html.twig - default page templatelayouts/list.html.twig - section/home/term listing templatelayouts/blog/list.rss.twig - RSS template for blog sectionlayouts/page.html.fr.twig - French page templatelayouts/_default/page.html.twig - fallback templatelayout template exists, use it first.index.* -> home.* -> list.* -> _default/*page.* -> _default/page.*list.* -> _default/*_default/* fallback.In practice, you usually need only:
layouts/page.html.twiglayouts/list.html.twiglayouts/_default/ or per sectionMost useful variables in Twig:
site.title, site.baseurl, site.descriptionsite.pages - pages collection (current language)site.allpages - pages in all languagessite.taxonomies - vocabularies and termssite.menus.<name> - menu entriespage.title, page.date, page.content, page.path, page.type, page.sectionUseful collection helpers:
site.pages.showable to skip draft/virtual/excluded pagessort_by_weight filter for menu entries{# layouts/page.html.twig #}
<!DOCTYPE html>
<html lang="{{ site.language }}">
<head>
<meta charset="utf-8">
<title>{{ page.title }} - {{ site.title }}</title>
{{ include('partials/metatags.html.twig') }}
</head>
<body>
<header>
<h1><a href="{{ url('/') }}">{{ site.title }}</a></h1>
{% if site.menus.main is defined %}
<nav>
<ul>
{% for entry in site.menus.main|sort_by_weight %}
<li><a href="{{ url(entry.url) }}">{{ entry.name }}</a></li>
{% endfor %}
</ul>
</nav>
{% endif %}
</header>
<main>
<article>
<h2>{{ page.title }}</h2>
{% if page.date %}
<time datetime="{{ page.date|date('c') }}">{{ page.date|date('Y-m-d') }}</time>
{% endif %}
{{ page.content }}
</article>
</main>
</body>
</html>
partials/metatags.html.twig - SEO/social tagspartials/navigation.html.twig - navigation helperpartials/paginator.html.twig - pagination linkspartials/languages.html.twig - language switcherIf needed, extract built-in templates to customize them:
php cecil.phar util:templates:extract
Core Twig helpers commonly used in Cecil templates:
url() - generate internal/absolute URLs depending on configasset() - reference and process assetsinclude() - compose templates with partials/componentsConfigure asset optimization:
assets:
minify: true
fingerprint: true
compile:
style: compressed
images:
optimize: true
draft: true to exclude non-published content from buildsExtend Cecil by creating custom generators:
<?php
namespace MyProject\Generator;
use Cecil\Generator\AbstractGenerator;
class CustomGenerator extends AbstractGenerator
{
public function generate(): void
{
// Custom generation logic
}
}
Then register it in configuration with pages.generators.
Create CLI commands by extending AbstractCommand:
<?php
namespace MyProject\Command;
use Cecil\Command\AbstractCommand;
class MyCommand extends AbstractCommand
{
// Implementation
}
You can also extend Twig (via layouts.extensions) and post-process output (via output.postprocessors).
Cecil generates pure static HTML, compatible with:
# Build
php cecil.phar build
# Deploy output directory (_site/)
# to your hosting platform
php cecil.phar build
# Commit _site/ directory and push to gh-pages branch
When extending or contributing to Cecil:
declare(strict_types=1); in all PHP files\ (e.g., \count())<?php
/**
* This file is part of Cecil.
*
* (c) Arnaud Ligny <arnaud@ligny.fr>
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/
pages/blog/index.md for blog sectionpages/blog/post-*.mdcecil buildpages/ directorylayouts/cecil.yml syntax and configurationpages/ directoryphp cecil.phar build -vv for verbose outputphp cecil.phar cache:clearGet detailed build information:
php cecil.phar build -v # Verbose
php cecil.phar build -vv # Very verbose
php cecil.phar build -vvv # Debug