cecilapp/cecil
Build and configure Cecil static sites, with focused guidance for content, templates, and site generation.
npx skills add https://github.com/Cecilapp/Cecil --skill cecilYou 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
Step/): Sequential build phasesGenerator/): Page generators executed via priority queueRenderer/): Twig-based rendering with custom extensions_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
Take cecilapp/cecil from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.