Menu
Build and configure Cecil static sites, with focused guidance for content, templates, and site generation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
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. |
| license | EUPL-1.2 |
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
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 clear | Remove generated files |
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 templates first.| Page Kind | Step 1 | Step 2 | Step 3 | Step 4 |
|---|---|---|---|---|
| Homepage | index.* | home.* | list.* | _default/* |
| Standard page | page.* | _default/page.* | - | - |
| Section page | section-specific list.* or explicit layout.* | list.* | _default/* | - |
| Taxonomy page | taxonomy template or explicit layout.* | list.* | _default/* | - |
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.sectionConfigure languages in cecil.yml:
language: en
languages:
- code: en
name: English
locale: en_US
- code: fr
name: Francais
locale: fr_FR
Use suffixed filenames for translations:
pages/about.md
pages/about.fr.md
You can render a language switcher in templates with:
{% include 'partials/languages.html.twig' %}
Useful 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
Pagination is configured globally under pages.pagination, and can be overridden in section front matter.
pages:
pagination:
max: 5
path: page
In list templates, include paginator links with:
{% include 'partials/paginator.html.twig' %}
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.
pages:
generators:
100: MyProject\\Generator\\CustomGenerator
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).
layouts:
extensions:
MyExtension: MyProject\\Twig\\MyExtension
The Twig extension class should implement Twig\Extension\ExtensionInterface (or extend Twig\Extension\AbstractExtension).
output:
postprocessors:
MyProcessor: MyProject\\Renderer\\PostProcessor\\MyProcessor
Post-processors should implement Cecil\Renderer\PostProcessor\PostProcessorInterface.
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())pages/blog/index.md for blog sectionpages/blog/post-*.mdphp cecil.phar buildpages/ directorylayouts/pages/search.json.md with front matter output: jsonlayouts/search.json.twig that iterates site.pages.showable and emits a JSON array of {title, url, content} objectsWhen a user reports unexpected behavior or asks about a specific feature, ask them to run php cecil.phar doctor and include the output. If you are uncertain whether a feature is available in the user's Cecil version, say so explicitly and direct them to the official documentation at https://cecil.app/documentation/ rather than guessing version ranges.
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