Cecil est distribué sous la forme d’un unique fichier exécutable, cecil.phar, qui fonctionne partout où PHP est installé.

Prérequis

• PHP 8.3+
• Extensions PHP : fileinfo, gd et mbstring

Vérifiez votre version de PHP et les extensions chargées :

php -v
php -m

Extensions optionnelles

Télécharger le PHAR

Téléchargez cecil.phar depuis votre terminal :

curl -LO https://cecil.app/cecil.phar

Puis exécutez-le avec PHP :

php cecil.phar --version

Installation globale

Installer Cecil globalement permet d’exécuter la commande cecil depuis n’importe quel dossier, au lieu de php cecil.phar.

macOS et Linux

Avec Homebrew :

brew install cecilapp/tap/cecil

Ou manuellement, en déplaçant le PHAR dans un dossier de votre PATH :

mv cecil.phar /usr/local/bin/cecil
chmod +x /usr/local/bin/cecil

Windows

Avec Scoop :

scoop install https://cecil.app/scoop/cecil.json

Ou manuellement :

1. Déplacez cecil.phar dans un dossier dédié tel que C:\bin
2. Renommez cecil.phar en cecil
3. Ajoutez ;C:\bin à votre variable d’environnement PATH
4. Créez un « wrapping batch script » à côté

PHIVE

Avec PHIVE (The PHAR Installation and Verification Environment) :

phive install cecil

Composer

Avec Composer :

composer global require cecil/cecil

Vérifier l’installation

cecil --version

Mise à jour

Mettez à jour Cecil vers la dernière version selon votre méthode d’installation :

# PHAR
php cecil.phar self-update
# Homebrew
brew upgrade cecilapp/tap/cecil
# Scoop
scoop update cecil
# PHIVE
phive update cecil
# Composer
composer global update cecil/cecil

La commande self-update (PHAR uniquement) accepte également les options suivantes :

• --rollback : revient à la version précédemment installée
• --stable : force la mise à jour vers la dernière version stable
• --preview : force la mise à jour vers la dernière version instable

Dépannage

command not found: cecil

Le dossier d’installation n’est pas dans votre PATH : ajoutez-le, ou exécutez Cecil avec php cecil.phar depuis le dossier contenant le PHAR.

Erreur de version ou d’extension PHP

Le PHP utilisé en ligne de commande peut différer de celui attendu (plusieurs versions installées) : vérifiez-le avec php -v et php --ini, puis activez les extensions manquantes dans le fichier php.ini chargé.

Diagnostiquer un site

Une fois un site créé, exécutez la commande doctor pour diagnostiquer sa configuration.

Diagramme

graph TD
    %% Entrée
    CLI["bin/cecil\n(Point d'entrée CLI)"]
    APP["Application\n(Symfony Console)"]
    CMD["Commandes\nbuild / serve / new:site\nnew:page / clear / show:content"]

    CLI --> APP --> CMD

    %% Orchestrateur
    BUILDER["Builder\n(Orchestrateur)"]
    CONFIG["Configuration\n(config.yml + default.php\n+ thèmes)"]
    CMD --> BUILDER
    CONFIG --> BUILDER

    %% Pipeline
    subgraph PIPELINE["Pipeline de génération (étapes)"]
        S1["1. Pages/Load\n(Finder → fichiers Markdown)"]
        S2["2. Data/Load\n(fichiers YAML)"]
        S3["3. StaticFiles/Load\n(chargement des fichiers statiques)"]
        S4["4. Pages/Create\n(création des objets Page)"]
        S5["5. Pages/Convert\n(Markdown → HTML\nfront matter)"]
        S6["6. Taxonomies/Create\n(création des taxonomies)"]
        S7["7. Pages/Generate\n(générateurs)"]
        S8["8. Menus/Create\n(création des menus)"]
        S9["9. StaticFiles/Copy\n(copie des fichiers statiques)"]
        S10["10. Pages/Render\n(rendu Twig)"]
        S11["11. Pages/Save\n(sauvegarde des pages)"]
        S12["12. Assets/Save\n(sauvegarde des assets)"]
        S13["13. Optimize/*\n(optimisation HTML/CSS/JS/Images)"]

        S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10 --> S11 --> S12 --> S13
    end

    BUILDER --> PIPELINE

    %% Sous-systèmes
    subgraph COLLECTIONS["Collections"]
        PC["PagesCollection\n(objets Page)"]
        TC["TaxonomiesCollection\n(vocabulaires/termes)"]
        MC["MenusCollection"]
    end

    subgraph GENERATORS["Générateurs (virtuels)"]
        GP["Pagination"]
        GT["Taxonomie"]
        GS["Section"]
        GR["Redirection"]
        GD["DefaultPages (accueil, 404)"]
    end

    subgraph RENDERER["Rendu Twig"]
        TW["Moteur Twig"]
        EXT["Extensions\n(Core, Content, Collection)"]
        PP["PostProcessors\n(métadonnées, extraits, liens)"]
        TH["Thèmes / Layouts"]
        TW --> EXT
        TW --> PP
        TH --> TW
    end

    subgraph ASSETS["Assets"]
        AL["Localisateur d'assets"]
        AC["Compilateur\n(SCSS → CSS)"]
        AI["Processeur d'images\n(responsive, WebP, AVIF)"]
        AO["Optimiseur\n(minification CSS/JS)"]
    end

    subgraph OUTPUT["Sortie (_site/)"]
        HTML["pages .html"]
        CSS2["assets CSS/JS"]
        IMG["images"]
        SF["fichiers statiques"]
    end

    S4 --> PC
    S6 --> TC
    S8 --> MC
    S7 --> GENERATORS
    GENERATORS --> PC
    S10 --> RENDERER
    S12 --> ASSETS

    PC --> RENDERER
    TC --> RENDERER
    MC --> RENDERER

    RENDERER --> S11
    S11 --> HTML
    S12 --> CSS2
    S12 --> IMG
    S9 --> SF

    %% Entrées
    subgraph INPUT["Sources"]
        MD["content/\n(Markdown + front matter)"]
        DATA["data/\n(YAML)"]
        STATIC["static/"]
        LAYOUTS["layouts/\n(modèles Twig)"]
    end

    MD --> S1
    DATA --> S2
    STATIC --> S3
    LAYOUTS --> TH

Légende des composants clés

image_srcset

Construit l'attribut HTML img srcset (responsive) d'un élément d'image.

{{ image_srcset(asset) }}

Exemples :

{% set asset = asset(image_path) %}
<img src="{{ url(asset) }}" width="{{ asset.width }}" height="{{ asset.height }}" alt="" class="asset" srcset="{{ image_srcset(asset) }}" sizes="{{ image_sizes('asset') }}">

image_sizes

Renvoie l'attribut HTML img sizes basé sur un nom de classe CSS. Il doit être utilisé conjointement avec la fonction image_srcset.

{{ image_sizes('class') }}

Exemples :

{% set asset = asset(image_path) %}
<img src="{{ url(asset) }}" width="{{ asset.width }}" height="{{ asset.height }}" alt="" class="asset" srcset="{{ image_srcset(asset) }}" sizes="{{ image_sizes('asset') }}">

image_from_website

Construit l'élément HTML img à partir d'une URL de site Web en extrayant son image d'illustration. Retourne null si aucune image n'est trouvée.

{{ image_from_website('url', {attributs}, {options}) }}

L'image est recherchée dans le HTML de la page avec les fallbacks suivants, le premier candidat pouvant être téléchargé en tant qu'image est utilisé :

1. Open Graph : og:image:secure_url, og:image, og:image:url
2. Twitter : twitter:image, twitter:image:src
3. <link rel="image_src">
4. Microdata : itemprop="image"
5. JSON-LD : propriété image
6. Première <img> de <article>, <main> ou <body>
7. <link rel="apple-touch-icon">
8. <link rel="icon">

Les URL relatives sont résolues par rapport à <base href> ou à l'URL de la page.

L'URL de l'image trouvée et l'image téléchargée sont mises en cache (voir cache.assets.remote.ttl).

Options :

• fallback : chemin (ou URL) de l'image utilisée si aucune image n'est trouvée
• autres options de image (ex. : responsive, formats)

Exemples :

{{ image_from_website('https://example.com/page-with-image.html') }}

{# avec une image de fallback #}
{{ image_from_website('https://example.com/', {alt: 'Illustration'}, {fallback: 'images/default.png'}) }}

resize

Redimensionne une image à une largeur (en pixels) ou/et une hauteur (en pixels) spécifiée.

• Si seule la largeur est spécifiée, la hauteur est calculée pour conserver le rapport hauteur/largeur
• Si seule la hauteur est spécifiée, la largeur est calculée pour conserver le rapport hauteur/largeur
• Si la largeur et la hauteur sont spécifiées, l'image est redimensionnée pour s'adapter aux dimensions données, l'image est recadrée et centrée si nécessaire
• Si Remove_animation est vrai, toute animation dans l'image (par exemple, GIF) sera supprimée

{{ asset(image_path)|resize(width: width, height: height, remove_animation: bool) }}

Exemples :

{{ asset(page.image)|resize(300) }}
{# equivalent to: #}
{{ asset(page.image)|resize(width: 300) }}
{# resizes to 300px width, height auto-calculated to preserve aspect ratio #}
{{ asset(page.image)|resize(height: 200) }}
{# resizes to 300px width and 200px height, and crops if necessary #}
{{ asset(page.image)|resize(300, 200) }}
{# removes any animation from the image #}
{{ asset(page.image)|resize(width: 1200, height: 630, remove_animation: true) }}

cover

Redimensionne une image à une largeur et une hauteur spécifiées, en la recadrant si nécessaire.

{{ asset(image_path)|cover(width, height) }}

Exemple:

{{ asset(page.image)|cover(1200, 630) }}

maskable

Ajoute un remplissage, en pourcentages, à une image pour la rendre masquable.

{{ asset(image_path)|maskable(padding) }}

Exemple:

{{ asset('icon.png')|maskable }}

webp

Convertit une image au format WebP.

Exemple:

<picture>
    <source type="image/webp" srcset="{{ asset(image_path)|webp }}">
    <img src="{{ url(asset(image_path)) }}" width="{{ asset(image_path).width }}" height="{{ asset(image_path).height }}" alt="">
</picture>

avif

Convertit une image au format AVIF.

Exemple:

<picture>
    <source type="image/avif" srcset="{{ asset(image_path)|avif }}">
    <img src="{{ url(asset(image_path)) }}" width="{{ asset(image_path).width }}" height="{{ asset(image_path).height }}" alt="">
</picture>

lqip

Renvoie un espace réservé pour une image de faible qualité (100 x 100 px, flou à 50 %) comme URL de données.

{{ asset(image_path)|lqip }}

dominant_color

Renvoie la couleur hexadécimale dominante d'une image.

{{ asset(image_path)|dominant_color }}

Organisation des fichiers

Types de templates

Il existe trois types de templates, layouts, components et autres templates : layouts sont utilisés pour afficher les pages, et chacun d'eux peut inclure des templates et components.

Convention de nommage

Les fichiers templates sont stockés dans le répertoire layouts/ et doivent être nommés selon la convention suivante :

layouts/(<section>/)<type>|<layout>.<format>(.<language>).twig

<section> (facultatif)

La section de la page (ex. : blog).

<type>

Le type de page : home (ou index) pour homepage, list pour list, page pour page, etc. (Voir Règles de recherche pour plus de détails).

<layout> (facultatif)

Le nom de la layout personnalisée défini dans le front-matter de la page (par exemple : layout: my-layout).

<format>

Le format de sortie de la page rendue (par exemple : html, rss, json, xml, etc.).

<language> (facultatif)

La langue de la page (ex. : fr).

Exemples :

layouts/home.html.twig       # `type` est "homepage"
layouts/page.html.twig       # `type` est "page"
layouts/page.html.fr.twig    # `type` est "page" et `language` est "fr"
layouts/my-layout.html.twig  # `layout` est "my-layout"
layouts/blog/list.html.twig  # `section` est "blog"
layouts/blog/list.rss.twig   # `section` est "blog" et `format` est "rss"

<mon-site>
├─ ...
├─ layouts
|  ├─ index.html.twig      # Utilisé par le type "homepage"
|  ├─ list.html.twig       # Utilisé par les types "homepage" et "section"
|  ├─ list.rss.twig        # Utilisé par les types "homepage" et "section", pour le format de sortie RSS
|  ├─ page.html.twig       # Utilisé par le type "page"
|  ├─ taxonomy
|  |  ├─ tags.html.twig    # Utilisé par le type "vocabulary" de `tags` (liste des termes)
|  |  └─ tag.html.twig     # Utilisé par le type "term" de `tags` (liste des pages)
|  ├─ my-layout.html.twig  # Utilisé par les pages avec `layout: my-layout` dans le front-matter
|  ├─ ...
|  └─ partials
|     ├─ footer.html.twig  # Template inclus
|     └─ ...
└─ themes                  # Layouts et templates des thèmes
   └─ ...

Templates intégrés

Cecil est livré avec un ensemble de templates intégrés.

Règles de recherche

Dans la plupart des cas vous n'avez pas besoin de préciser la layout : Cecil sélectionne la layout la plus appropriée, en fonction du type de la page.

Par exemple, la sortie HTML de home page (index.md) sera rendue :

1. avec my-layout.html.twig si la variable layout est définie sur "my-layout" (dans le préambule)
2. sinon, avec index.html.twig si le fichier existe
3. sinon, avec home.html.twig si le fichier existe
4. sinon, avec list.html.twig si le fichier existe

Toutes les règles sont détaillées ci-dessous, pour chaque type de page, par ordre de priorité.

Type homepage

1. <layout>.<format>.twig
2. index.<format>.twig
3. home.<format>.twig
4. list.<format>.twig
5. _default/<layout>.<format>.twig
6. _default/index.<format>.twig
7. _default/home.<format>.twig
8. _default/list.<format>.twig
9. _default/page.<format>.twig

Type page

1. <section>/<layout>.<format>.twig
2. <layout>.<format>.twig
3. <section>/page.<format>.twig
4. _default/<layout>.<format>.twig
5. page.<format>.twig
6. _default/page.<format>.twig

Type section

1. <layout>.<format>.twig
2. <section>/index.<format>.twig
3. <section>/list.<format>.twig
4. section/<section>.<format>.twig
5. <parent>/index.<format>.twig, <parent>/list.<format>.twig et section/<parent>.<format>.twig, pour chaque section parente d’une sous-section (la plus proche en premier)
6. _default/section.<format>.twig
7. list.<format>.twig
8. _default/list.<format>.twig

Type vocabulary

1. taxonomy/<plural>.<format>.twig
2. vocabulary.<format>.twig
3. _default/vocabulary.<format>.twig

Type term

1. taxonomy/<plural>/<term>.<format>.twig
2. taxonomy/<singular>.<format>.twig
3. term.<format>.twig
4. _default/term.<format>.twig
5. _default/list.<format>.twig

Fonctions peut être appelée pour générer du contenu. Les fonctions sont appelées par leur nom suivi de parenthèses (()) et peuvent avoir des arguments.

url

Crée une URL valide pour une page, une entrée de menu, un actif, un ID de page ou un chemin.

{{ url(value, {options}) }}

Exemples :

{# page #}
{{ url(page) }}
{{ url(page, {canonical: true}) }}
{{ url(page, {format: json}) }}
{{ url(page, {language: fr}) }}
{# menu entry #}
{{ url(site.menus.main.about) }}
{# asset #}
{{ url(asset('styles.css')) }}
{# page ID #}
{{ url('page-id') }}
{# path #}
{{ url('about-me/') }}
{{ url('tags/' ~ tag) }}

html

Crée un élément HTML à partir d'un actif (ou d'un tableau d'actifs avec des attributs personnalisés).

{{ html(asset, {attributes}, {options}) }}
{# dedicated functions for each common type of asset #}
{{ css(asset) }}
{{ js(asset) }}
{{ image(asset) }}
{{ audio(asset) }}
{{ video(asset) }}

Exemples :

{# CSS with an attribute #}
{{ html(asset('print.css'), {media: 'print'}) }}
{# CSS with an attribute and an option #}
{{ html(asset('styles.css'), {title: 'Main theme'}, {preload: true}) }}
{# Array of assets with media query #}
{{ html([
  {asset: asset('css/style.css')},
  {asset: asset('css/style-dark.css'), attributes: {media: '(prefers-color-scheme: dark)'}}
]) }}
{# JavaScript #}
{{ html(asset('script.js')) }}
{# image without specific attributes nor options #}
{{ html(asset('image.png')) }}
{# image with specific attributes, responsive images and alternative formats #}
{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {responsive: true, formats: ['avif', 'webp']}) }}
{# image with responsive pixels density images #}
{{ html(asset('image.jpg'), options={responsive: 'density'}, attributes={width: 256}) }}
{# image with a Low-Quality Image Placeholder #}
{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {placeholder: 'lqip'}) }}
{# Audio #}
{{ html(asset('audio.mp3')) }}
{# Video #}
{{ html(asset('video.mp4')) }}

readtime

Détermine le temps de lecture d'un texte, en minutes.

{{ readtime(value) }}

Exemple:

{{ readtime(page.content) }} min

hash

Calcule le hachage d'un objet, d'un tableau ou d'une chaîne avec un algorithme donné.

{{ hash(value, algorithm) }}

algorithm peut être n'importe quel algorithme pris en charge par la fonction hash() de PHP (par exemple : md5, sha256, etc.). La valeur par défaut est xxh128.

Exemple:

{{ hash('my string', 'sha256') }}

cache_key

Calcule une clé de cache pour fragments cache en fonction d'un nom et d'une valeur facultative.

{% cache cache_key(name, value) %}
  {# cacheable content #}
{% endcache %}

La fonction ajoute un hachage de la valeur (peut être une chaîne, un tableau ou un objet) au nom (ainsi que la langue actuelle et l'ID de build pour être sûr que la clé de cache générée est unique), donc si la valeur est modifiée, la clé de cache est également modifiée et le cache est automatiquement vidé.

getenv

Obtient la valeur d'une variable d'environnement à partir de sa clé.

{{ getenv(var) }}

Exemple:

{{ getenv('VAR') }}

dump

La fonction dump affiche les informations sur une variable de modèle. Ceci est surtout utile pour déboguer un modèle qui ne se comporte pas comme prévu en introspectant ses variables :

{{ dump(user) }}

d

La fonction d() est la version HTML de dump() et utilise le Symfony VarDumper Component en arrière-plan.

{{ d(variable, {theme: light}) }}

• Si variable n'est pas fourni, la fonction renvoie le contexte Twig actuel
• Les thèmes disponibles sont « clair » (par défaut) et « sombre »

fingerprint

Ajoutez l'empreinte digitale du contenu du fichier au nom du fichier.

{{ asset(path)|fingerprint }}
{{ path|fingerprint }}

Exemples :

{{ asset('styles.css')|fingerprint }}

minify

Réduire un fichier CSS ou JavaScript.

{{ asset(path)|minify }}

Exemples :

{{ asset('styles.css')|minify }}
{{ asset('scripts.js')|minify }}

minify_css

Réduire une chaîne CSS.

{{ variable|minify_css }}

{% apply minify_css %}
{# CSS here #}
{% endapply %}

Exemples :

{% set styles = 'some CSS here' %}
{{ styles|minify_css }}

<style>
{% apply minify_css %}
  html {
    background-color: #fcfcfc;
    color: #444;
  }
{% endapply %}
</style>

minify_js

Réduire une chaîne JavaScript.

{{ variable|minify_js }}

{% apply minify_js %}
{# JavaScript here #}
{% endapply %}

Exemples :

{% set script = 'some JavaScript here' %}
{{ script|minify_js }}

<script>
{% apply minify_js %}
  var test = 'test';
  console.log(test);
{% endapply %}
</script>

scss_to_css

Compile une chaîne Sass en CSS.

{{ variable|scss_to_css }}

{% apply scss_to_css %}
{# SCSS here #}
{% endapply %}

Alias : sass_to_css.

Exemples :

{% set scss = 'some SCSS here' %}
{{ scss|scss_to_css }}

<style>
{% apply scss_to_css %}
  $color: #fcfcfc;
  div {
    color: lighten($color, 20%);
  }
{% endapply %}
</style>

to_css

Compile un fichier Sass en CSS.

{{ asset(path)|to_css }}
{{ path|to_css }}

Exemples :

{{ asset('styles.scss')|to_css }}

inline

Affiche le contenu d'un Asset.

{{ asset(path)|inline }}

Exemple:

{{ asset('styles.css')|inline }}

dataurl

Renvoie l'URL de données d'un actif.

{{ asset(path)|dataurl }}
{{ asset(image_path)|dataurl }}

L'application transmet des variables aux templates pour manipulation dans le modèle. Les variables peuvent également avoir des attributs ou des éléments auxquels vous pouvez accéder. Utilisez un point (.) pour accéder aux attributs d'une variable : {{ foo.bar }}

Vous pouvez utiliser des variables de différentes portées : site, page, cecil.

site

La variable site contient des variables intégrées et celles définies dans la configuration.

Exemple:

title: "My amazing website!"

Peut être affiché dans un modèle avec :

{{ site.title }}

site.menus

Bouclez sur site.menus.<menu> pour obtenir chaque entrée de la collection <menu> (par exemple : main).

Exemple:

<nav>
  <ol>
  {% for entry in site.menus.main|sort_by_weight %}
    <li><a href="{{ url(entry.url) }}" data-weight="{{ entry.weight }}">{{ entry.name }}</a></li>
  {% endfor %}
  </ol>
</nav>

site.language

Informations sur la langue actuelle.

site.static

La collection de fichiers statiques est accessible via site.static si le static load est activé.

Chaque fichier expose les propriétés suivantes :

• path : chemin relatif (ex. : /images/img-1.jpg)
• date : date de création (timestamp)
• updated : date de modification (timestamp)
• name : nom (ex. : img-1.jpg)
• basename : nom sans extension (ex. : img-1)
• ext : poste (ex. : jpg)
• type : type de média (ex. : image)
• subtype : sous-type de média (ex. : image/jpeg)
• exif : données EXIF ​​​​de l'image (array)
• audio : Mp3Info objet
• video : tableau d'informations vidéo de base (durée en secondes, largeur et hauteur)

site.data

Une collection de données est accessible via site.data.<filename> (sans extension de fichier).

Exemples :

• data/authors.yml : site.data.authors
• data/authors.fr.yml : site.data.authors (si site.language = "fr")
• data/galleries/gallery-1.json : site.data.galleries['gallery-1']

page

La variable page contient les variables intégrées d'une page et celles définies dans le avant-plan.

Sections imbriquées

Dans un contexte de sections imbriquées, les propriétés page.parent, page.ancestors, page.sections et page.toplevel facilitent la construction de la navigation.

Fil d'Ariane (de la page d'accueil à la page courante) :

<nav aria-label="breadcrumb">
  <ul>
    <li><a href="{{ url(site.home) }}">{{ site.title }}</a></li>
    {% for section in page.ancestors|reverse %}
    <li><a href="{{ url(section) }}">{{ section.title }}</a></li>
    {% endfor %}
    {% if page.id != site.home %}
    <li><a href="{{ url(page) }}" aria-current="page">{{ page.title }}</a></li>
    {% endif %}
  </ul>
</nav>

Menu des sous-sections (sections descendantes immédiates de la section courante) :

{% if page.sections|length %}
<ul>
  {% for section in page.sections|sort_by_title %}
  <li><a href="{{ url(section) }}">{{ section.title }}</a></li>
  {% endfor %}
</ul>
{% endif %}

Navigation principale limitée aux sections de premier niveau (depuis n'importe quelle page) :

<nav>
  {% for section in site.page(site.home).sections|sort_by_title %}
  <a href="{{ url(section) }}">{{ section.title }}</a>
  {% endfor %}
</nav>

Lien vers la section parente :

{% if page.parent %}
<a href="{{ url(page.parent) }}">← {{ page.parent.title }}</a>
{% endif %}

page.<prev/next>

Navigation entre les pages d'une même Section, triées selon le sortby de la section (ordre chronologique pour les dates).

Avec des sous-sections, la navigation suit l'arbre des sections : les pages d'une Section de premier niveau et de toutes ses sous-sections sont enchaînées, chaque sous-section (sa page d'index) étant placée parmi les pages de sa Section parente et suivie de ses propres pages.

Exemple:

<a href="{{ url(page.prev) }}">{{ page.prev.title }}</a>

page.paginator

Paginator vous aide à créer une navigation pour les pages de la liste : page d'accueil, sections et taxonomies.

Exemple:

{% if page.paginator %}
<div>
  {% if page.paginator.links.prev is defined %}
  <a href="{{ url(page.paginator.links.prev) }}">Previous</a>
  {% endif %}
  {% if page.paginator.links.next is defined %}
  <a href="{{ url(page.paginator.links.next) }}">Next</a>
  {% endif %}
</div>
{% endif %}

Exemple:

{% if page.paginator %}
<div>
  {% for paginator_index in 1..page.paginator.count %}
    {% if paginator_index != page.paginator.current %}
      {% if paginator_index == 1 %}
  <a href="{{ url(page.paginator.links.first) }}">{{ paginator_index }}</a>
      {% else %}
  <a href="{{ url(page.paginator.links.path ~ '/' ~ paginator_index) }}">{{ paginator_index }}</a>
      {% endif %}
    {% else %}
  {{ paginator_index }}
    {% endif %}
  {% endfor %}
</div>
{% endif %}

Taxonomie

Variables disponibles dans les templates vocabulary et term.

Vocabulaire

Page /<plural>/ (ex. : /categories/).

Chaque terme de page.terms fournit term.id (identifiant du terme, ex. : categories/php), term.name (nom du terme, ex. : PHP) et le nombre de ses pages avec term|length.

Terme

Page /<plural>/<term>/ (ex. : /categories/php/).

Exemple de taxonomie

Configuration :

taxonomies:
  categories: category

Front matter d’une page :

---
categories: ["Data Sovereignty"]
---

Liste des termes (/categories/), dans layouts/taxonomy/categories.html.twig :

{% extends 'page.html.twig' %}

{% block content %}
  <h1>{{ page.title }}</h1>
  <ul>
  {% for term in page.terms %}
    <li><a href="{{ url(term.id) }}">{{ term.name }}</a> ({{ term|length }})</li>
  {% endfor %}
  </ul>
{% endblock %}

Liste des pages d’un terme (/categories/data-sovereignty/), dans layouts/taxonomy/category.html.twig :

{% extends 'page.html.twig' %}

{% block content %}
  <h1>{{ page.title }}</h1>
  {% for p in page.paginator.pages ?? page.pages %}
    <article>
      <h2><a href="{{ url(p) }}">{{ p.title }}</a></h2>
    </article>
  {% endfor %}
  <a href="{{ url(page.plural) }}">Toutes les {{ page.plural }}</a>
{% endblock %}

Liens vers les termes de la page courante, dans un template de page :

{% for category in page.categories ?? [] %}
  <a href="{{ url('categories/' ~ category) }}">{{ category }}</a>
{% endfor %}

cecil

Tri des collections (de pages, menus ou taxonomies).

sort_by_title

Trie une collection par titre (avec tri naturel).

{{ collection|sort_by_title }}

Exemple:

{{ site.pages|sort_by_title }}

sort_by_date

Trie une collection par date (la plus récente en premier).

{{ collection|sort_by_date(variable='date', desc_title=false) }}

Exemple:

{# sort by date #}
{{ site.pages|sort_by_date }}
{# sort by updated variable instead of date #}
{{ site.pages|sort_by_date(variable='updated') }}
{# sort items with the same date by desc title #}
{{ site.pages|sort_by_date(desc_title=true) }}
{# reverse sort #}
{{ site.pages|sort_by_date|reverse }}

sort_by_weight

Trie une collection par poids (le plus léger en premier).

{{ collection|sort_by_weight }}

Exemple:

{{ site.menus.main|sort_by_weight }}

sort

Pour les cas plus complexes, vous devez utiliser le sort natif de Twig.

Exemple:

{% set files = site.static|sort((a, b) => a.date|date('U') < b.date|date('U')) %}

Les variables peuvent être modifiées par filtres. Les filtres sont séparés de la variable par un symbole de barre verticale (|). Plusieurs filtres peuvent être chaînés. La sortie d’un filtre est appliquée au suivant.

{{ page.title|truncate(25)|capitalize }}

filter_by

Filtre une collection de pages par nom/valeur de variable.

{{ collection|filter_by(variable, value) }}

Exemple:

{{ pages|filter_by('section', 'blog') }}

filter

Pour les cas plus complexes, vous devez utiliser le filter natif de Twig.

Exemple:

{% pages|filter(p => p.virtual == false and p.id not in ['page-1', 'page-2']) %}

markdown_to_html

Convertit une chaîne Markdown en HTML.

{{ markdown|markdown_to_html }}

{% apply markdown_to_html %}
{# Markdown here #}
{% endapply %}

Exemples :

{% set markdown = '**This is bold text**' %}
{{ markdown|markdown_to_html }}

{% apply markdown_to_html %}
**This is bold text**
{% endapply %}

toc

Extrait uniquement les en-têtes correspondant au selectors donné (h2, h3, etc.), ou à ceux définis dans la configuration pages.body.toc s'ils ne sont pas spécifiés. Le paramètre format définit le format de sortie : html ou json. Le paramètre url est utilisé pour créer des liens vers des titres.

{{ markdown|toc(format, selectors, url) }}

Exemples :

{{ page.body|toc }}
{{ page.body|toc('html') }}
{{ page.body|toc(selectors=['h2']) }}
{{ page.body|toc(url=url(page)) }}

json_decode

Convertit une chaîne JSON en tableau.

{{ json|json_decode }}

Exemple:

{% set json = '{"foo": "bar"}' %}
{% set array = json|json_decode %}
{{ array.foo }}

yaml_parse

Convertit une chaîne YAML en tableau.

{{ yaml|yaml_parse }}

Exemple:

{% set yaml = 'key: value' %}
{% set array = yaml|yaml_parse %}
{{ array.key }}

slugify

Convertit une chaîne en slug.

{{ string|slugify }}

u

Le filtre u enveloppe un texte dans un objet Unicode (une instance Symfony UnicodeString) qui expose des méthodes pour « manipuler » la chaîne.

Exemple:

{{ 'cecil_string with twig'|u.camel.title }}

CecilStringAvecTwig

singular

Le filtre singular transforme un nom donné au pluriel en sa version singulière.

{{ string|singular(locale)}}

Exemple:

{# English (en) rules are used by default #}
{{ 'partitions'|singular }}

partition

{{ 'partitions'|singular('fr') }}

partition

plural

Le filtre plural transforme un nom donné au singulier en sa version plurielle.

{{ string|plural(locale)}}

Exemple:

{# English (en) rules are used by default #}
{{ 'animal'|plural }}

animaux

{{ 'animal'|plural('fr') }}

animaux

excerpt

Tronque une chaîne et ajoute un suffixe.

{{ string|excerpt(length, suffix) }}

Exemples :

{{ variable|excerpt }}
{{ variable|excerpt(250, '...') }}

excerpt_html

Lit les caractères avant ou après la balise <!-- excerpt --> ou <!-- break -->. Voir Documentation de contenu pour plus de détails.

{{ string|excerpt_html({separator, capture}) }}

Exemples :

{{ variable|excerpt_html }}
{{ variable|excerpt_html({separator: 'excerpt|break', capture: 'before'}) }}
{{ variable|excerpt_html({capture: 'after'}) }}

highlight

Met en surbrillance une chaîne de code avec highlight.php.

{{ code|highlight(language) }}

Exemples :

{{ '<?php echo $highlighted->value; ?>'|highlight('php') }}

preg_split

Divise une chaîne en un tableau à l'aide d'une expression régulière.

{{ string|preg_split(pattern, limit) }}

Exemple:

{% set headers = page.content|preg_split('/<br[^>]*>/') %}

preg_match_all

Effectue une correspondance d'expression régulière et renvoie le groupe pour toutes les correspondances.

{{ string|preg_match_all(pattern, group) }}

Exemple:

{% set tags = page.content|preg_match_all('/<[^>]+>(.*)<\/[^>]+>/') %}

hex_to_rgb

Convertit une couleur hexadécimale en RVB.

{{ color|hex_to_rgb }}

Cecil fournit une logique de composants pour vous donner le pouvoir de créer des "unités" de templates réutilisables.

Syntaxe des composants

Les composants ne sont que des templates Twig stockés dans le sous-répertoire components/ et peuvent être utilisés n'importe où dans vos templates :

{# /components/button.twig #}
<button {{ attributes.merge({class: 'rounded px-4'}) }}>
    {{ slot }}
</button>

La variable slot correspond à tout contenu que vous ajouterez entre la balise d'ouverture et la balise de fermeture.

Pour accéder à un composant vous devez utiliser la balise dédiée x suivie de : et du nom de fichier de votre composant sans extension :

{# /index.twig #}
{% x:button with {class: 'text-white'} %}
    <strong>Click me</strong>
{% endx %}

Il rendra :

<button class="text-white rounded px-4">
    <strong>Click me</strong>
</button>

Cecil prend en charge traduction du texte et localisation de la date.

Traduction de texte

Utilise le trans tag ou filter pour traduire des textes dans des templates.

{% trans with variables into locale %}{% endtrans %}

{{ message|trans(variables = []) }}

Exemples

{% trans %}Hello World!{% endtrans %}

{{ message|trans }}

Inclure des variables :

{% trans with {'%name%': 'Arnaud'} %}Hello %name%!{% endtrans %}

{{ message|trans({'%name%': 'Arnaud'}) }}

Forcer les paramètres régionaux :

{% trans into 'fr_FR' %}Hello World!{% endtrans %}

Pluraliser :

{% trans with {'%count%': 42}%}{0}I don't have apples|{1}I have one apple|]1,Inf[I have %count% apples{% endtrans %}

Fichiers de traduction

Les fichiers de traduction doivent être nommés messages.<locale>.<extension> et stockés dans le répertoire translations. Les extensions prises en charge sont définies pour chaque format de traduction dans layouts.translations.formats.

Le code locale (ex. : fr_FR) d'une langue est défini dans les entrées languages de la configuration.

Exemple:

<mywebsite>
└─ translations
   ├─ messages.fr_FR.mo   <- Machine Object format
   └─ messages.fr_FR.yaml <- Yaml format

Localisation de la date

Utilise le filtre Twig format_date pour localiser une date dans les templates.

{{ page.date|format_date('long') }}
{# September 30, 2022 #}

Les valeurs prises en charge sont : short, medium, long et full.

Cecil utilise un système de cache pour accélérer le processus de génération, il peut être désactivé ou effacé.

Il existe trois types de cache dans le cas du rendu des templates : les templates eux-mêmes, assets et translations.

Vider le cache

Vous pouvez vider le cache avec les commandes suivantes :

php cecil.phar cache:clear               # clear all caches
php cecil.phar cache:clear:assets        # clear assets cache
php cecil.phar cache:clear:templates     # clear templates cache
php cecil.phar cache:clear:translations  # clear translations cache

Fragments de cache

Cecil fournit un moyen de mettre en cache des parties du rendu des templates pour éviter de restituer plusieurs fois le même contenu partiel.

Pour utiliser les fragments de cache, vous devez envelopper le contenu que vous souhaitez mettre en cache avec la balise cache.

{% cache 'unique-key' %}
  {# cacheable content #}
{% endcache %}

Pour vider uniquement le cache des fragments, vous pouvez utiliser la commande suivante :

php cecil.phar cache:clear:templates --fragments

Désactiver le cache

Vous pouvez désactiver le cache avec la configuration.

Fonctions et filtres

Vous pouvez ajouter des fonctions et des filtres personnalisés avec une extension Twig.

Thème

C'est simple de construire un thème, il suffit de créer un dossier <theme> avec la structure suivante (comme un site web mais sans pages) :

<mywebsite>
└─ themes
   └─ <theme>
      ├─ config.yml
      ├─ assets
      ├─ layouts
      ├─ static
      └─ translations

Crée un nouveau site.

Description:
  Creates a new website

Usage:
  new:site [options] [--] [<path>]

Arguments:
  path                  Use the given path as working directory

Options:
  -f, --force           Override directory if it already exists
      --demo            Add demo content (pages, templates and assets)
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The new:site command creates a new website in the current directory, or in <path> if provided.
  If you run this command without any options, it will ask you for the website title, baseline, base URL, description, etc.

    cecil.phar new:site
    cecil.phar new:site path/to/the/working/directory

  To create a new website with demo content, run:

    cecil.phar new:site --demo

  To override an existing website, run:

    cecil.phar new:site --force

title

Titre principal du site.

title: "<site title>"

baseline

Description courte (~ 20 caractères).

baseline: "<baseline>"

baseurl

URL de base.

baseurl: <url>

Exemple :

baseurl: http://localhost:8000/

canonicalurl

Si la valeur est true, la fonction url() renverra l’URL absolue (false par défaut).

canonicalurl: <true|false> # false by default

description

Description du site (~ 250 caractères).

description: "<description>"

menus

Les menus sont utilisés pour créer des liens de navigation dans les templates.

Un menu est composé d’un identifiant unique et des propriétés des entrées (nom, URL, poids).

menus:
  <name>:
    - id: <unique-id>   # unique identifier (required)
      name: "<name>"    # name displayed in templates
      url: <url>        # relative or absolute URL
      weight: <integer> # integer value used to sort entries (lighter first)

Exemple :

menus:
  main:
    - id: about
      name: "About"
      url: /about/
      weight: 1
  footer:
    - id: author
      name: The author
      url: https://arnaudligny.fr
      weight: 99

Surcharger une entrée

Une entrée de menu de page peut être surchargée : utilisez l’ID de la page comme id.

Exemple :

menus:
  main:
    - id: index
      name: "My amazing homepage!"
      weight: 1

Désactiver une entrée

Une entrée de menu peut être désactivée avec enabled: false.

Exemple :

menus:
  main:
    - id: about
      enabled: false

taxonomies

Liste des vocabulaires, associant une valeur au pluriel à une valeur au singulier.

taxonomies:
  <plural>: <singular>

Exemple :

taxonomies:
  categories: category
  tags: tag

Vous pouvez ensuite utiliser ces vocabulaires dans le front matter de votre contenu.

theme

Thème à utiliser, ou liste de thèmes.

theme: <theme> # theme name
# or
theme:
  - <theme1> # theme name
  - <theme2>

Exemples :

theme: hyde

theme:
  - serviceworker
  - hyde

date

Format de date et fuseau horaire.

date:
  format: <format>     # date format (optional, `F j, Y` by default)
  timezone: <timezone> # date timezone (optional, local time zone by default)

• format : spécificateur de format de date PHP
• timezone : voir les fuseaux horaires

Exemple :

date:
  format: 'j F, Y'
  timezone: 'Europe/Paris'

metatags

Les metatags sont des aides SEO et réseaux sociaux qui peuvent être injectées automatiquement dans le <head>, via le template partials/metatags.html.twig.

Ce template ajoute les balises meta suivantes :

• Titre de page + titre du site, ou titre du site + baseline du site
• Description de la page/du site
• Mots-clés de la page/du site
• Auteur de la page/du site
• Directives des robots des moteurs de recherche (robots)
• Liens de favicon
• Liens de navigation (premier, précédent, suivant, dernier)
• URL canonique
• Liens alternatifs (ex. : flux RSS, autres langues)
• Liens rel=me
• Open Graph
• Identifiant de profil Facebook
• Twitter/X Card
• Fediverse tag
• Dublin Core
• Structured data (JSON-LD)

options metatags

Cecil utilise le front matter de la page pour alimenter les meta tags, avec repli sur les options du site si nécessaire.

title: "Page/Site title"              # used by title meta
description: "Page/Site description"  # used by description meta
tags: [tag1, tag2]                    # used by keywords meta
keywords: [keyword1, keyword2]        # obsolete
author:                               # used by author meta
  name: <name>                          # author name
  url: <url>                            # author URL
  email: <email>                        # author email
image: image.jpg                      # used by Open Graph and social networks cards
canonical:                            # used to override the generated canonical URL
  url: <URL>                            # absolute URL
  title: "<URL title>"                  # optional canonical title
social:                               # used by social networks meta
  twitter:                              # used by Twitter/X Card
    url: <URL>                            # used for `rel=me` link
    site: username                        # site username
    creator: username                     # page author username
  mastodon:                             # used by Mastodon meta
    url: <URL>                            # used for `rel=me` link
    creator: handle                       # page author account
  facebook:                             # used by Facebook meta
    url: <URL>                            # used for `rel=me` link
    id: 123456789                         # Facebook profile ID
    username: username                    # page author username

configuration metatags

metatags:
  title:                   # title options
    divider: " · "    # string between page title and site title
    only: false              # displays page title only (`false` by default)
    pagination:              # pagination options
      shownumber: true         # displays page number in title (`true` by default)
      label: "Page %s"         # how to display page number (`Page %s` by default)
  robots: "index,follow"   # web crawlers directives (`index,follow` by default)
  favicon:                 # favicon options
    enabled: true            # includes favicon (`true` by default)
    image: favicon.png       # path to favicon image
    sizes:                   # sizes by device
      - "icon": [32, 57, 76, 96, 128, 192, 228]  # web browsers
      - "shortcut icon": [196]                   # Android
      - "apple-touch-icon": [120, 152, 180]      # iOS
  navigation: true         # includes previous and next links (`true` by default)
  image: true              # includes image (`true` by default)
  og: true                 # includes Open Graph meta tags (`true` by default)
  articles: "blog"         # articles' section (`blog` by default)
  twitter: true            # includes Twitter/X Card meta tags (`true` by default)
  mastodon: true           # includes Mastodon meta tags (`true` by default)
  dc: false                # includes Dublin Core meta tags (`false` by default)
  data: false              # includes JSON-LD structured data (`false` by default)

debug

Active le mode debug, utilisé pour afficher des informations de débogage comme des journaux très verbeux, le dump Twig, le profileur Twig, le sourcemap SCSS, etc.

debug: true

Il existe deux autres façons d’activer le mode debug :

1. Exécuter une commande avec l’option -vvv
2. Définir la variable d’environnement CECIL_DEBUG à true

Une page est un fichier composé d’un front matter et d’un body.

Front matter

Le front matter est une collection de variables (au format clé/valeur) entourée par ---.

Exemple :

---
title: "The title"
date: 2019-02-21
tags: [tag 1, tag 2]
customvar: "Value of customvar"
---

Corps (body)

Le body est le contenu principal d’une page ; il peut être écrit en Markdown ou en texte brut.

Exemple :

# Header

[toc]

## Sub-Header 1

Lorem ipsum dolor [sit amet](https://example.com), consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<!-- excerpt -->
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Sub-Header 2

![Description](/image.jpg "Title")

## Sub-Header 3

:::tip
This is advice.
:::

Préfixe de fichier

Le nom de fichier peut contenir un préfixe pour définir les variables date ou weight de la page (utilisé par sortby).

date

Le date prefix est utilisé pour définir la date de la page et doit être un format de date valide (c.-à-d. : « YYYY-MM-DD »).

Exemple :

Dans « 2019-04-23_My blog post.md » :

• le préfixe est « 2019-04-23 »
• la date de la page est « 2019-04-23 »
• le title de la page est « My blog post »

weight

Le weight prefix est utilisé pour définir l’ordre de tri de la page et doit être une valeur entière valide.

Exemple :

Dans « 1_The first project.md » :

• le préfixe est « 1 »
• le weight de la page est « 1 »
• le title de la page est « The first project »

Section

Certaines variables dédiées peuvent être utilisées dans une Section personnalisée (c.-à-d. : <section>/index.md).

sortby

L’ordre des pages dans une Section peut être modifié.

Valeurs disponibles :

• date: plus récentes en premier
• title: ordre alphabétique
• weight: plus léger en premier

Exemple :

---
sortby: title
---

More options:

---
sortby:
  variable: date    # "date", "updated", "title" or "weight"
  desc_title: false # used with "date" or "updated" variable value to sort by desc title order if items have the same date
  reverse: false    # reversed if true
---

pagination

La configuration globale de pagination est utilisée par défaut, mais vous pouvez la modifier pour une Section donnée.

Exemple :

---
pagination:
  max: 5
  path: "page"
---

La pagination peut être désactivée pour une Section :

---
pagination: false
---

cascade

Toutes les variables de cascade sont ajoutées au front matter de toutes les sous-pages.

Exemple :

---
cascade:
  banner: image.jpg
---

circular

Définissez circular à true pour activer la navigation circulaire avec page.<prev/next>.

Exemple :

---
circular: true
---

Sous-section

Un dossier imbriqué qui contient explicitement un fichier index.md devient une sous-section de sa Section parente.

<monsiteweb>
└─ pages
   └─ blog                 <- Section
      ├─ index.md
      ├─ post-1.md         <- Page de la Section « blog »
      └─ 2024              <- Sous-section (contient un « index.md »)
         ├─ index.md
         └─ post-2.md      <- Page de la Section « blog » *et* de la sous-section « blog/2024 »

Une sous-section :

• est une Section (même type, mêmes variables et même résolution de gabarit) accessible à sa propre URL (ex. : /blog/2024/)
• est rendue avec les gabarits de ses Sections parentes si elle n'a pas les siens (ex. : blog/list.html.twig)
• peut être imbriquée à n'importe quelle profondeur (ex. : blog/2024/06/)
• liste ses propres pages, et ses pages appartiennent aussi à chacune de leurs Sections parentes
• n'est pas listée dans sa Section parente
• est placée dans la navigation page.<prev/next> de sa Section parente (selon son sortby), suivie de ses propres pages

Page d'accueil

Comme une autre section, la Page d'accueil prend en charge la configuration sortby et pagination.

pagesfrom

Définissez un nom de Section valide dans pagesfrom pour utiliser la collection de pages de cette Section dans la Page d'accueil.

Exemple :

---
pagesfrom: blog
---

Netlify

Une puissante plateforme serverless avec un flux de travail intuitif basé sur Git. Déploiements automatisés, aperçus partageables, et bien plus encore.

➡️ https://www.netlify.com

netlify.toml:

[build]
  publish = "_site"
  command = "curl -sSOL https://cecil.app/build.sh && bash ./build.sh"
[context.production.environment]
  CECIL_ENV = "production"
[context.deploy-preview.environment]
  CECIL_ENV = "preview"

Documentation officielle

Vercel

Vercel associe une excellente expérience développeur à une attention obsessionnelle portée aux performances côté utilisateur final.

➡️ https://vercel.com

vercel.json:

{
  "buildCommand": "curl -sSOL https://cecil.app/build.sh && bash ./build.sh",
  "outputDirectory": "_site"
}

Documentation officielle

statichost

Hébergement moderne de sites statiques avec des serveurs européens et absolument aucune collecte de données personnelles !

➡️ https://statichost.eu

statichost.yml:

image: wordpress:cli-php8.4
command: curl -sSOL https://cecil.app/build.sh && bash ./build.sh
public: _site

Documentation officielle

Cloudflare Pages

Cloudflare Pages est une plateforme JAMstack qui permet aux développeurs frontend de collaborer et de déployer des sites web.

➡️ https://pages.cloudflare.com

Configurations de build :

• Préréglage de framework : None
• Commande de build : curl -sSOL https://cecil.app/build.sh && bash ./build.sh
• Répertoire de sortie du build : _site

Documentation officielle

Render

Render est un cloud unifié pour créer et exécuter toutes vos applications et tous vos sites web, avec certificats TLS gratuits, CDN global, réseaux privés et déploiements automatiques depuis Git.

➡️ https://render.com

render.yaml:

previewsEnabled: true
services:
  - type: web
    name: Cecil
    env: static
    buildCommand: curl -sSOL https://cecil.app/build.sh && bash ./build.sh
    staticPublishPath: _site
    pullRequestPreviewsEnabled: true

Documentation officielle

Comme Cecil repose sur PHP, il est facile d'en étendre les capacités.

Générateur de pages

Un générateur permet de créer des pages sans fichiers Markdown (avec des données provenant d'une API ou d'une base de données, par exemple), ou de modifier des pages existantes.

Créez simplement une nouvelle classe PHP dans l'espace de noms Cecil\Generator, puis ajoutez le nom de la classe à la liste pages.generators.

Exemple:

/extensions/Cecil/Generator/DummyPage.php

<?php
namespace Cecil\Generator;

use Cecil\Collection\Page\Page;
use Cecil\Collection\Page\Type;

class DummyPage extends AbstractGenerator implements GeneratorInterface
{
    public function generate(): void
    {
        // create a new page $page, then add it to the site collection
        $page = (new Page('my-page'))
            ->setType(Type::PAGE->value)
            ->setPath('mypage')
            ->setBodyHtml('<p>My page body</p>')
            ->setVariable('language', 'en')
            ->setVariable('title', 'My page')
            ->setVariable('date', now())
            ->setVariable('menu', ['main' => ['weight' => 99]]);
        $this->generatedPages->add($page);
    }
}

/extensions/Cecil/Generator/Database.php

<?php
namespace Cecil\Generator;

use Cecil\Collection\Page\Page;
use Cecil\Collection\Page\Type;

class Database extends AbstractGenerator implements GeneratorInterface
{
    public function generate(): void
    {
        // create pages from a SQLite database
        $db = new SQLite3('database.sqlite');
        $statement = $db->prepare('SELECT * FROM blog');
        $result = $statement->execute();
        while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
            $page = (new Page($row['page-id']))
                ->setType(Type::PAGE->value)
                ->setPath($row['path'])
                ->setBodyHtml($row['html'])
                ->setVariable('title', $row['title'])
                ->setVariable('date', $row['date']);
            $this->generatedPages->add($page);
        }
        $result->finalize();
        $db->close();
    }
}

configuration

pages:
  generators:
    # priority: class name
    99: Cecil\Generator\DummyPage
    35: Cecil\Generator\Database

Extension Twig

Vous pouvez ajouter des fonctions et des filtres personnalisés :

1. créez une extension Twig dans l'espace de noms Cecil\Renderer\Extension
2. ajoutez le fichier PHP dans le répertoire extensions
3. ajoutez le nom de la classe à la configuration

Exemple:

/extensions/Cecil/Renderer/Extension/MyTwigExtension.php

<?php
namespace Cecil\Renderer\Extension;

class MyTwigExtension extends \Twig\Extension\AbstractExtension
{
    public function getFilters()
    {
        // add a new filter named 'md5'
        return [
            new \Twig\TwigFilter('md5', 'md5'),
        ];
    }
}

configuration

layouts:
  extensions:
    MyExtension: Cecil\Renderer\Extension\MyTwigExtension

Post-processeur de rendu

Vous pouvez post-traiter le rendu des pages.

Créez simplement une nouvelle classe PHP dans l'espace de noms Cecil\Renderer\PostProcessor et ajoutez le nom de la classe à la liste output.postprocessors.

Exemple:

/extensions/Cecil/Renderer/PostProcessor/MyProcessor.php

<?php
namespace Cecil\Renderer\PostProcessor;

use Cecil\Collection\Page\Page;

class MyProcessor extends AbstractPostProcessor
{
    public function process(Page $page, string $output, string $format): string
    {
        // add a meta tag to the head of the HTML output
        if ($format == 'html') {
            if (!preg_match('/<meta name="test".*/i', $output)) {
                $meta = \sprintf('<meta name="test" content="Test">');
                $output = preg_replace_callback('/([[:blank:]]*)(<\/head>)/i', function ($matches) use ($meta) {
                    return str_repeat($matches[1] ?: ' ', 2) . $meta . "\n" . $matches[1] . $matches[2];
                }, $output);
            }
        }

        return $output;
    }
}

configuration

output:
  postprocessors:
    MyProcessor: Cecil\Renderer\PostProcessor\MyProcessor

Crée une nouvelle page.

Description:
  Creates a new page

Usage:
  new:page [options] [--] [<path>]

Arguments:
  path                        Use the given path as working directory

Options:
      --name=NAME             Page path name
      --slugify|--no-slugify  Slugify file name (or disable --no-slugify)
  -p, --prefix                Prefix the file name with the current date (`YYYY-MM-DD`)
  -f, --force                 Override the file if already exist
  -o, --open                  Open editor automatically
      --editor=EDITOR         Editor to use with open option
  -h, --help                  Display help for the given command. When no command is given display help for the list command
  -q, --quiet                 Do not output any message
  -V, --version               Display this application version
      --ansi|--no-ansi        Force (or disable --no-ansi) ANSI output
  -n, --no-interaction        Do not ask any interactive question
  -v|vv|vvv, --verbose        Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The new:page command creates a new page file.
  If you run this command without any options, it will ask you for the page name and other options.

    cecil.phar new:page
    cecil.phar new:page --name=path/to/a-page.md
    cecil.phar new:page --name=path/to/A Page.md --slugify

  To create a new page with a date prefix (i.e: `YYYY-MM-DD`), run:

    cecil.phar new:page --prefix

  To create a new page and open it with an editor, run:

    cecil.phar new:page --open --editor=editor

  To override an existing page, run:

    cecil.phar new:page --force

Modèles de page

Vous pouvez définir vos propres modèles pour vos nouvelles pages dans le répertoire models :

1. Le nom doit être basé sur le nom de la section (par exemple : blog.md)
2. Le modèle par défaut doit être nommé default.md (pour les pages racine ou les sections de pages sans modèle)

Deux variables dynamiques sont disponibles :

1. %title% : le nom du fichier
2. %date% : la date actuelle

Ouvrir avec votre éditeur

Avec l’option --open, l’éditeur s’ouvrira automatiquement. Utilisez donc la clé editor dans votre fichier de configuration pour définir l’éditeur par défaut (par exemple : editor: typora).

language

Langue principale, définie par son code.

language: <code> # unique code (`en` by default)

Par défaut, seuls les chemins des pages des autres langues sont préfixés par leur code de langue, mais vous pouvez préfixer le chemin des pages de la langue principale avec l’option suivante :

#language: <code>
language:
  code: <code>
  prefix: true

languages

Options des langues disponibles, utilisées pour la localisation des pages et des templates.

languages:
  - code: <code>          # unique code (e.g.: `en`, `fr`, 'en-US', `fr-CA`)
    name: <name>          # human readable name (e.g.: `Français`)
    locale: <locale>      # locale code (`language_COUNTRY`, e.g.: `en_US`, `fr_FR`, `fr_CA`)
    enabled: <true|false> # enabled or not (`true` by default)

Exemple :

language: en
languages:
  - code: en
    name: English
    locale: en_US
  - code: fr
    name: Français
    locale: fr_FR

Localiser

Pour localiser des options de configuration, vous devez les stocker sous la clé config de la langue.

Exemple :

title: "Cecil in english"
languages:
  - code: en
    name: English
    locale: en_US
  - code: fr
    name: Français
    locale: fr_FR
    config:
      title: "Cecil en français"

Le front matter peut contenir des variables personnalisées appliquées à la page courante.

Il doit se trouver au tout début du fichier et être un YAML valide.

Variables prédéfinies

updated

La variable updated sert à définir la date de dernière modification d’une page.

Exemple :

---
updated: 2026-02-02
---

menu

Une page peut être ajoutée à un menu.

Le nom de l’entrée est le title de la page et l’URL est le path de la page.

La même page peut être ajoutée à plusieurs menus, et la position de chaque entrée peut être définie avec la clé weight (la plus faible en premier). La clé name peut être utilisée pour personnaliser le nom de l’entrée par menu.

Exemples :

---
menu: main
---

---
menu: [main, navigation] # same page in multiple menus
---

---
menu:
  main:
    weight: 10
  navigation:
    weight: 20
---

---
title: 'Notre expertise'
menu:
  main:
    weight: 15
  footer:
    weight: 15
    name: "Expertise" # personnalise le nom de l'entrée dans ce menu
---

Taxonomie

La taxonomie permet de connecter, relier et classer le contenu de votre site Web.
Dans Cecil, ces termes sont regroupés dans des vocabulaires.

Les vocabulaires sont déclarés dans la Configuration.

Vocabulaire

Une catégorisation du contenu (ex. : tags, categories, etc.).

Terme

Un terme est un élément d’un vocabulaire (ex. : Développement, PHP, etc.).

Exemple :

---
tags: ["Développement", "PHP"]
---

Cecil génère ensuite, pour chaque vocabulaire :

• une page listant ses termes, ex. : /tags/
• une page par terme listant ses pages, ex. : /tags/developpement/ et /tags/php/

Voir les règles de recherche des templates et les variables de taxonomie pour personnaliser ces pages.

Planification

Planifie la publication des pages.

Exemple :

La page sera publiée si la date courante est >= 2023-02-07 :

schedule:
  publish: 2023-02-07

Cette page est publiée si la date courante est <= 2022-04-28 :

schedule:
  expiry: 2022-04-28

redirect

Comme son nom l’indique, la variable redirect sert à rediriger une page vers une URL dédiée.

Exemple :

---
redirect: "https://arnaudligny.fr"
---

alias

Un alias est une redirection vers la page courante.

Exemple :

---
title: "About"
alias:
  - contact
---

Dans l’exemple précédent, contact/ redirige vers about/.

output

Définit le format de sortie de la page.

Les formats disponibles sont : html, atom, rss, json, xml, etc.
Vous pouvez définir un ou plusieurs formats dans un tableau.

Il n’est pas obligatoire de définir un format de sortie, mais si vous le faites, il doit correspondre à l’un des formats disponibles définis dans la Configuration.

Exemple :

---
output: [html, atom]
---

external

Une page avec une variable external tente de récupérer le contenu de la ressource ciblée.

Exemple :

---
external: "https://raw.githubusercontent.com/Cecilapp/Cecil/main/README.md"
---

excluded

Définissez excluded à true pour masquer une page des pages de liste (c.-à-d. : Home page, Section, Sitemap, etc.).

Exemple :

---
excluded: true
---

GitHub Pages

Des sites web pour vous et vos projets, hébergés directement depuis votre dépôt GitHub. Il suffit de modifier, pousser, et vos changements sont en ligne.

➡️ https://pages.github.com

.github/workflows/build-and-deploy.yml:

name: Build and deploy to GitHub Pages
on:
  push:
    branches: [master, main]
  workflow_dispatch:
concurrency:
  group: pages
  cancel-in-progress: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v6
      - name: Restore Cecil cache
        uses: actions/cache/restore@v5
        with:
          path: ./.cache
          key: cecil-cache-
          restore-keys: |
            cecil-cache-
      - name: Build site
        uses: Cecilapp/Cecil-Action@v4
      - name: Save Cecil cache
        uses: actions/cache/save@v5
        with:
          path: ./.cache
          key: cecil-cache-${{ hashFiles('./.cache/**/*') }}
  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

Documentation officielle

GitLab CI

Avec GitLab Pages, vous pouvez publier des sites web statiques directement depuis un dépôt GitLab.

➡️ https://about.gitlab.com/solutions/continuous-integration/

.gitlab-ci.yml:

image: wordpress:cli-php8.4
test:
  stage: test
  variables:
    CECIL_OUTPUT_DIR: test
  script:
    - curl -sSOL https://cecil.app/build.sh && bash ./build.sh
  artifacts:
    paths:
     - test
  except:
   - master
pages:
  stage: deploy
  variables:
    CECIL_ENV: production
    CECIL_OUTPUT_DIR: public
  script:
    - curl -sSOL https://cecil.app/build.sh && bash ./build.sh
  artifacts:
    paths:
      - public
  only:
    - master
cache:
  paths:
    - composer-cache/
    - vendor/
    - .cache/

Documentation officielle

Cecil propose une API PHP simple pour générer votre site web.

Vous pouvez consulter la documentation de l'API pour plus de détails.

Installation

composer require cecil/cecil

Support de libvips

Pour traiter les images avec libvips (optionnel), installez le driver libvips dans votre projet :

composer require intervention/image-driver-vips

Utilisation

Construction

Construisez un nouveau site web avec une configuration personnalisée :

require_once 'vendor/autoload.php';

use Cecil\Builder;

$config = [
    'title'   => "My website",
    'baseurl' => 'https://domain.tld/',
];

Builder::create($config)->build();

exec('php -S localhost:8000 -t _site'); // prévisualisation locale

Diagnostic

Vous pouvez aussi exécuter les vérifications doctor via des services de domaine dédiés, sans utiliser les commandes CLI.

<?php

require_once 'vendor/autoload.php';

use Cecil\Builder;
use Cecil\Doctor\SeoDoctor;
use Cecil\Doctor\SiteDoctor;

$builder = Builder::create(require 'config.php')
    ->setSourceDir(__DIR__)
    ->setDestinationDir(__DIR__);

$siteDoctor = new SiteDoctor();
$diagnosis = $siteDoctor->diagnose($builder, __DIR__, ['cecil.yml']);

$seoDoctor = new SeoDoctor();
$seoAudit = $seoDoctor->audit($builder, [
    'page' => '',
    'include_virtual' => false,
]);

var_dump($diagnosis['errors'], $seoAudit['summary']);

Construit et sert le site en local.

Description:
  Starts the built-in server

Usage:
  serve [options] [--] [<path>]

Arguments:
  path                             Use the given path as working directory

Options:
  -o, --open                       Open web browser automatically
      --host=HOST                  Server host [default: "localhost"]
      --port=PORT                  Server port [default: "8000"]
  -w, --watch|--no-watch           Enable (or disable --no-watch) changes watcher (enabled by default)
  -i, --incremental                Enable incremental builds (rebuild only changed pages)
  -d, --drafts                     Include drafts
      --optimize|--no-optimize     Enable (or disable --no-optimize) optimization of generated files
  -c, --config=CONFIG              Set the path to extra config files (comma-separated)
      --clear-cache[=CLEAR-CACHE]  Clear cache before build (optional cache key as regular expression) [default: false]
  -p, --page=PAGE                  Build a specific page
      --no-ignore-vcs              Changes watcher must not ignore VCS directories
  -m, --metrics                    Show build metrics (duration and memory) of each step
      --timeout=TIMEOUT            Sets the process timeout (max. runtime) in seconds [default: 7200]
      --notify                     Send desktop notification on server start
  -b, --background                 Run the server in the background
  -h, --help                       Display help for the given command. When no command is given display help for the list command
  -q, --quiet                      Do not output any message
  -V, --version                    Display this application version
      --ansi|--no-ansi             Force (or disable --no-ansi) ANSI output
  -n, --no-interaction             Do not ask any interactive question
  -v|vv|vvv, --verbose             Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The serve command starts the live-reloading-built-in web server.

    cecil.phar serve
    cecil.phar serve path/to/the/working/directory
    cecil.phar serve --open
    cecil.phar serve --drafts
    cecil.phar serve --no-watch

  To speed up local development you can enable incremental builds with the --incremental option.
  When content pages change, Cecil rebuilds just those pages.
  When templates change, Cecil rebuilds only pages using those templates (including Twig dependencies such as extends/include).
  Any other change (data, config, static or asset file, or file deletion) triggers a full rebuild:

    cecil.phar serve --incremental

  You can use a custom host and port by using the --host and --port options:

    cecil.phar serve --host=127.0.0.1 --port=8080

  To build the website with an extra configuration file, you can use the --config option.
  This is useful during local development to override some settings without modifying the main configuration:

    cecil.phar serve --config=config/dev.yml

  To start the server with changes watcher not ignoring VCS directories, run:

    cecil.phar serve --no-ignore-vcs

  To define the process timeout (in seconds), run:

    cecil.phar serve --timeout=7200

  To run the server in the background, run:

    cecil.phar serve --background
    cecil.phar serve -b

  Then stop it with:

    cecil.phar serve:stop

  In background mode, file changes are not watched automatically.

serve:background

Alias de serve --background : démarre le serveur intégré en arrière-plan sans occuper le terminal.

Description:
  Starts the built-in server in the background (alias of `serve --background`)

Usage:
  serve:background [options] [--] [<path>]

Help:
  The serve:background command starts the built-in web server in the background.

    cecil.phar serve:background
    cecil.phar serve:background path/to/the/working/directory

  This command is an alias of serve --background.

  Stop the server with:

    cecil.phar serve:stop

serve:log

Affiche les logs combinés du serveur et des erreurs, triés par date.

Description:
  Shows combined server and error logs

Usage:
  serve:log [options] [--] [<path>]

Arguments:
  path                  Use the given path as working directory

Options:
  -l, --lines=LINES     Number of entries to display (default: 25)

Help:
  The serve:log command displays entries from combined server and error logs, sorted by date.

    cecil.phar serve:log
    cecil.phar serve:log path/to/the/working/directory
    cecil.phar serve:log --lines=100
    cecil.phar serve:log -l 100

  This command shows logs from `.cecil/errors.log` and `.cecil/server.log`.
  It is useful for debugging issues with your local development server.

Cecil prend en charge le format Markdown, ainsi que Markdown Extra.

Cecil fournit aussi des fonctionnalités supplémentaires pour enrichir votre contenu, voir ci-dessous.

Attributs

Avec Markdown Extra, vous pouvez définir un id, une classe et des attributs personnalisés sur certains éléments à l’aide d’un bloc d’attributs.
Par exemple, placez le(s) attribut(s) souhaité(s) après un en-tête, un bloc de code délimité, un lien ou une image en fin de ligne, entre accolades, comme ceci :

## En-tête {#id .class attribute=value}

Liens

Vous pouvez créer un lien avec la syntaxe [Texte](url) ; url peut être un chemin, un chemin relatif vers un fichier Markdown, une URL externe, etc.

Exemple :

[Link to a path](/about/)
[Link to a Markdown file](/fr/a-propos/)
[Link to Cecil website](https://cecil.app)

Lien vers une page

Vous pouvez facilement créer un lien vers une page avec la syntaxe [Titre de page](page:page-id).

Exemple :

[Link to a blog post](page:blog/post-1)

Externe

Par défaut, les liens externes ont la valeur suivante pour l’attribut rel : noopener noreferrer.

Exemple :

<a href="<url>" rel="noopener noreferrer">Link to another website</a>

Vous pouvez modifier ce comportement avec les options pages.body.links.external.

Liens intégrés

Vous pouvez laisser Cecil essayer de transformer un lien en contenu embarqué en utilisant l’attribut {embed} ou en activant l’option de configuration globale pages.body.links.embed.enabled à true.

Exemple :

[CECIL : LE générateur de SITES STATIQUES en PHP](https://www.youtube.com/watch?v=ur8koU0iYvc){embed}

Local video/audio files

Cecil peut aussi créer des éléments HTML vidéo et audio, selon l’extension du fichier.

Exemple :

[Video file](video.mp4){embed controls poster=/images/video-test.png}
[Audio file](song.mp3){embed controls}

Est converti en :

<video src="/video.mp4" controls poster="/images/video-test.png" style="max-width:100%;height:auto;"></video>
<audio src="/song.mp3" controls></audio>

Images

Pour ajouter une image, utilisez un point d’exclamation (!) suivi d’une description alternative entre crochets ([]), puis du chemin ou de l’URL de l’image entre parenthèses (()).
Vous pouvez facultativement ajouter un titre entre guillemets.

![Alternative description](/image.jpg "Image title")

Lazy loading

Cecil ajoute l’attribut loading="lazy" à chaque image.

Exemple :

![](/image.jpg)

Est converti en :

<img src="/image.jpg" loading="lazy">

Decoding

Cecil ajoute l’attribut decoding="async" à chaque image.

Exemple :

![](/image.jpg)

Est converti en :

<img src="/image.jpg" decoding="async">

Redimensionnement

Chaque image du body peut être redimensionnée automatiquement en définissant une largeur inférieure à celle d’origine, avec l’attribut additionnel {width=X}.

Exemple :

![](/image.jpg){width=800}

Est converti en :

<img src="/thumbnails/800/image.jpg" width="800" height="600">

Formats

Si l’option formats est définie, des images alternatives sont créées et ajoutées.

Exemple :

![](/image.jpg)

Peut être converti en :

<picture>
  <source srcset="/image.avif" type="image/avif">
  <source srcset="/image.webp" type="image/webp">
  <img src="/image.jpg">
</picture>

Responsive

Si l’option responsive est activée, alors toutes les images du body seront automatiquement rendues « responsive ».

Exemple :

![](/image.jpg){width=800}

sera converti en :

<img src="/thumbnails/800/image.jpg" width="800" height="600"
  srcset="/thumbnails/320/image.jpg 320w,
          /thumbnails/640/image.jpg 640w,
          /thumbnails/800/image.jpg 800w"
  sizes="100vw"
>

L’attribut sizes prend la valeur de l’option de configuration assets.images.responsive.sizes.default, mais peut être modifié en créant une nouvelle entrée nommée d’après une class ajoutée à l’image.

Exemple :

assets:
  images:
    responsive:
      sizes:
        default: 100vw
        my_class: "(max-width: 800px) 768px, 1024px"

![](/image.jpg){.my_class}

CSS class

Vous pouvez définir une valeur par défaut pour l’attribut class de chaque image avec l’option class.

Caption

Le titre optionnel peut être utilisé pour créer automatiquement une légende (figcaption) en activant l’option caption.

Exemple :

![](/images/img.jpg "Title")

Est converti en :

<figure>
  <img src="/image.jpg" title="Title">
  <figcaption>Title</figcaption>
</figure>

Image localisée

Pour les pages traduites, Cecil recherche d’abord un fichier suffixé par la langue lors de la résolution des chemins d’image Markdown.

Exemple :

![](/images/cecil-logo.png)

Avec une page française (fr), Cecil essaie d’abord /images/cecil-logo.fr.png, puis revient à /images/cecil-logo.png.

Placeholder

Comme les images sont généralement des ressources plus lourdes et plus lentes, et qu’elles ne bloquent pas le rendu, il est préférable de donner aux utilisateurs quelque chose à voir pendant qu’ils attendent leur chargement.

L’attribut placeholder accepte 2 options :

1. color: affiche un fond coloré (basé sur la couleur dominante de l’image)
2. lqip: Low-Quality Image Placeholder

Exemples :

![](/images/img.jpg){placeholder=color}
![](/images/img.jpg){placeholder=lqip}

Table des matières

Vous pouvez ajouter une table des matières avec la syntaxe Markdown suivante :

[toc]

Extrait

Un extrait peut être défini dans le body avec l’une des balises suivantes : excerpt ou break.

Exemple :

Introduction.
<!-- excerpt -->
Main content.

Utilisez ensuite le filtre excerpt_html dans votre template.

Notes

Créez un bloc de Note (info, astuce, important, etc.).

Exemple :

:::tip
**Tip:** This is advice.
:::

Est converti en :

<aside class="note note-tip">
  <p>
    <strong>Tip:</strong> This is advice.
  </p>
</aside>

Autres exemples :

Coloration syntaxique

La coloration syntaxique des blocs de code est activée par défaut avec l’option pages.body.highlight.

Si besoin, vous pouvez la désactiver avec :

pages:
  body:
    highlight: false

Exemple :

```php
echo "Hello world";
```

Est rendu en :

echo "Hello world";

Texte inséré

Représente une plage de texte qui a été ajoutée.

++text++

Est converti en :

<ins>text</ins>

Surge

Publier des projets web doit être rapide, simple et peu risqué. Surge est un service de publication de sites statiques pour les développeurs frontend, directement depuis la CLI.

➡️ https://surge.sh

Terminal:

npm install -g surge
surge _site/

Documentation officielle

Arborescence du système de fichiers

Organisation des fichiers du projet.

<monsiteweb>
├─ pages
|  ├─ blog            <- Section
|  |  ├─ billet-1.md  <- Page dans Section
|  |  └─ billet-2.md
|  ├─ projets
|  |  └─ projet-a.md
|  └─ about.md        <- Page racine
├─ assets
|  ├─ styles.scss     <- Fichier d'asset
|  └─ logo.png
├─ static
|  └─ fichier.pdf     <- Fichier statique
└─ data
   └─ auteurs.yml     <- Collection de données

Arborescence du site généré

Résultat de la génération.

<monsiteweb>
└─ _site
   ├─ index.html               <- Page d'accueil générée
   ├─ blog/
   |  ├─ index.html            <- Liste des articles générée
   |  ├─ billet-1/index.html   <- Article de blog
   |  └─ billet-2/index.html
   ├─ projets/
   |  ├─ index.html            <- Liste des projets générée
   |  └─ projet-a/index.html   <- Projet individuel
   ├─ about/index.html         <- Page "À propos"
   ├─ styles.css
   ├─ logo.png
   └─ fichier.pdf

Routage basé sur les fichiers

Les fichiers Markdown du répertoire pages activent un routage basé sur les fichiers. Cela signifie que l’ajout, par exemple, de pages/mon-projet/projet-a.md le rendra accessible à l’URL /projet-a dans votre navigateur.

Fichier :
                   pages/mon-projet/projet-a.md
                        └───── filepath ──────┘
URL :
    ┌───── baseurl ─────┬─────── path ────────┐
     https://exemple.com/mon-projet/projet-a/index.html
                        └─ section ─┴─ slug ──┘

Construit le site.

Description:
  Builds the website

Usage:
  build [options] [--] [<path>]

Arguments:
  path                               Use the given path as working directory

Options:
  -d, --drafts                       Include drafts
  -u, --baseurl=BASEURL              Set the base URL
  -o, --output=OUTPUT                Set the output directory
      --optimize|--no-optimize       Enable (or disable --no-optimize) optimization of generated files
      --dry-run                      Build without saving
  -c, --config=CONFIG                Set the path to extra config files (comma-separated)
      --clear-cache[=CLEAR-CACHE]    Clear cache before build (optional cache key as regular expression) [default: false]
  -p, --page=PAGE                    Build a specific page
      --render-subset=RENDER-SUBSET  Render a subset of pages
      --show-pages                   Show list of built pages in a table
  -m, --metrics                      Show build metrics (duration and memory) of each step
      --notify                       Send desktop notification on build completion
  -h, --help                         Display help for the given command. When no command is given display help for the list command
  -q, --quiet                        Do not output any message
  -V, --version                      Display this application version
      --ansi|--no-ansi               Force (or disable --no-ansi) ANSI output
  -n, --no-interaction               Do not ask any interactive question
  -v|vv|vvv, --verbose               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The build command generates the website in the output directory.

    cecil.phar build
    cecil.phar build path/to/the/working/directory
    cecil.phar build --baseurl=https://example.com/
    cecil.phar build --output=_site

  To build the website with optimization of generated files, you can use the --optimize option.
  This is useful to reduce the size of the generated files and improve performance:

    cecil.phar build --optimize
    cecil.phar build --no-optimize

  To build the website without overwriting files in the output directory, you can use the --dry-run option.
  This is useful to check what would be built without actually writing files:

    cecil.phar build --dry-run

  To build the website with a specific subset of rendered pages, you can use the --render-subset option.
  This is useful to build only a part of the website, for example, only "hot" pages or a specific section:

    cecil.phar build --render-subset=subset

  To show build steps metrics, run:

    cecil.phar build --metrics

pages.dir

Répertoire source des pages (pages par défaut).

pages:
  dir: pages

pages.ext

Extensions des fichiers de pages.

pages:
  ext: [md, markdown, mdown, mkdn, mkd, text, txt]

pages.exclude

Répertoires, chemins et noms de fichiers à exclure (accepte les glob, les chaînes et les expressions régulières).

pages:
  exclude: ['vendor', 'node_modules', '*.scss', '/\.bck$/']

pages.prefix.separator

Liste des caractères utilisés comme séparateur entre un préfixe de nom de fichier (date ou weight) et le slug.

pages:
  prefix:
    separator: ['-', '_']

pages.sortby

Méthode de tri par défaut des collections.

pages:
  sortby: date # `date`, `updated`, `title` ou `weight`
  # ou
  sortby:
    variable: date    # `date`, `updated`, `title` ou `weight`
    desc_title: false # tri par titre décroissant
    reverse: false    # inverse l’ordre de tri

pages.pagination

La pagination est disponible pour les pages de liste (type homepage, section ou term).

pages:
  pagination:
    max: 5     # nombre maximum d’entrées par page
    path: page # chemin de la page paginée

Désactiver la pagination

La pagination peut être désactivée :

pages:
  pagination: false

pages.paths

Applique un path personnalisé à toutes les pages d’une section.

pages:
  paths:
    - section: <section’s ID>
      path: <path of pages>

Emplacements des variables de chemin

• :year
• :month
• :day
• :section
• :slug

Exemple :

pages:
  paths:
    - section: Blog
      path: :section/:year/:month/:day/:slug # ex. : /blog/2020/12/01/my-post/
# localized
languages:
  - code: fr
    name: Français
    locale: fr_FR
    config:
      pages:
        paths:
          - section: Blog
            path: blogue/:year/:month/:day/:slug # ex. : /blogue/2020/12/01/mon-billet/

pages.frontmatter

Format du front matter des pages (yaml par défaut, accepte aussi ini, toml et json).

pages:
  frontmatter: yaml

pages.body

Options du corps des pages.

pages.body.toc

En-têtes utilisés pour construire la table des matières ([h2, h3] par défaut).

pages:
  body:
    toc: [h2, h3]

pages.body.highlight

Active la coloration syntaxique du code (true par défaut).

pages:
  body:
    highlight: false # définissez à false pour désactiver la coloration syntaxique

pages.body.images

Options de gestion des images.

pages:
  body:
    images:
      formats: []       # ajoute des formats d’image alternatifs comme `source` (ex. `[avif, webp]`, tableau vide par défaut)
      resize: 0         # redimensionne toutes les images à <width> (en pixels, `0` pour désactiver)
      responsive: false # ajoute des variantes responsives à l’attribut `srcset` (`false` par défaut)
      lazy: true        # ajoute l’attribut `loading="lazy"` (`true` par défaut)
      decoding: true    # ajoute l’attribut `decoding="async"` (`true` par défaut)
      caption: false    # place l’image dans un élément <figure> et ajoute une <figcaption> contenant le titre (`false` par défaut)
      placeholder: ''   # remplit l’arrière-plan de <img> avant le chargement ('color' ou 'lqip', vide par défaut)
      class: ''         # définit une classe par défaut sur chaque image (vide par défaut)
      dark_suffix: ''   # suffixe de l’image variante sombre (ex. `.dark`), désactivé par défaut
      mobile_suffix: '' # suffixe de l’image variante mobile (ex. `.mobile`), désactivé par défaut
      mobile_media_query: '(max-width: 767px)' # media query de la `<source>` de la variante mobile
      remote:           # traitement des images distantes (mettre à `false` pour désactiver)
        fallback:         # chemin de l’image de secours, stockée dans le répertoire assets (vide par défaut)

pages.body.links

Options de gestion des liens.

pages:
  body:
    links:
      embed:
        enabled: false     # transforme les liens en contenu embarqué si possible (`false` par défaut)
        video: [mp4, webm] # extensions des fichiers vidéo
        audio: [mp3]       # extensions des fichiers audio
      external:
        blank: false     # si `true`, ouvre le lien externe dans un nouvel onglet
        noopener: true   # si `true`, ajoute `noopener` à l’attribut `rel`
        noreferrer: true # si `true`, ajoute `noreferrer` à l’attribut `rel`
        nofollow: false  # si `true`, ajoute `nofollow` à l’attribut `rel`

pages.body.excerpt

Options de gestion des extraits.

pages:
  body:
    excerpt:
      separator: excerpt|break # chaîne utilisée comme séparateur (`excerpt|break` par défaut)
      capture: before          # partie à capturer, `before` ou `after` le séparateur (`before` par défaut)

pages.virtual

Les pages virtuelles sont la meilleure façon de créer des pages sans contenu (front matter uniquement).

Elles consistent en une liste de pages avec un path et quelques variables de front matter.

Exemple :

pages:
  virtual:
    - path: code
      redirect: https://github.com/ArnaudLigny

pages.default

Les pages par défaut sont des pages créées automatiquement par Cecil (à partir de modèles intégrés) :

pages:
  default:
    index:
      path: ''
      title: Accueil
      published: true
    404:
      path: 404
      title: Page introuvable
      layout: 404
      uglyurl: true
      published: true
      excluded: true
    robots:
      path: robots
      title: Robots.txt
      layout: robots
      output: txt
      published: true
      excluded: true
      multilingual: false
    sitemap:
      path: sitemap
      title: Plan de site XML
      layout: sitemap
      output: xml
      changefreq: monthly
      priority: 0.5
      published: true
      excluded: true
      multilingual: false
    xsl/atom:
      path: xsl/atom
      layout: feed
      output: xsl
      uglyurl: true
      published: true
      excluded: true
    xsl/rss:
      path: xsl/rss
      layout: feed
      output: xsl
      uglyurl: true
      published: false
      excluded: true

Chaque page peut être :

1. désactivée : published: false
2. exclue des pages de liste : excluded: true
3. exclue de la localisation : multilingual: false

pages.generators

Les générateurs servent à Cecil pour créer des pages supplémentaires (par ex. sitemap, flux, pagination, etc.) à partir de pages existantes, ou à partir d’autres sources comme le fichier de configuration ou des sources externes.

Voici la liste des générateurs fournis par Cecil, dans un ordre défini :

pages:
  generators:
    10: 'Cecil\Generator\DefaultPages'
    20: 'Cecil\Generator\VirtualPages'
    30: 'Cecil\Generator\ExternalBody'
    40: 'Cecil\Generator\Section'
    50: 'Cecil\Generator\Taxonomy'
    60: 'Cecil\Generator\Homepage'
    70: 'Cecil\Generator\Pagination'
    80: 'Cecil\Generator\Alias'
    90: 'Cecil\Generator\Redirect'

pages.subsets

Les sous-ensembles servent à rendre une partie de la collection de pages, selon un chemin, une langue ou un format de sortie spécifique, avec la commande :

cecil build --render-subset=<name>

pages:
  subsets:
    <name>:
      path: <path> # chemin glob ou chaîne (ex. `blog/*`, `blog`)
      language: <language> # code de langue (ex. `en`, `fr`)
      output: <output> # format de sortie (ex. `html`, `atom`)

Exemple :

pages:
  subsets:
    blog_en:
      path: blog
      language: en
      output: html
    search_index:
      path: '*'
      output: json

Si vos pages sont disponibles en plusieurs langues, il existe 2 façons différentes de le définir :

Via le nom de fichier

C’est la méthode la plus courante pour traduire une page depuis la langue principale vers une autre langue.

Il suffit de dupliquer la page de référence et de lui ajouter en suffixe le code de la langue cible (ex. : fr).

Exemple :

├─ about.md    # the reference page
└─ about.fr.md # the french version (`fr`)

Via le front matter

Si vous souhaitez créer une page dans une langue autre que la langue principale, sans qu’elle soit la traduction d’une page existante, vous pouvez utiliser la variable language dans son front matter.

Exemple :

---
language: fr
---

Lier les pages traduites

Chaque page traduite référence les pages dans les autres langues.

Cette collection de pages est disponible dans les templates via la variable suivante :

{{ page.translations }}

Diagnostique le site courant et l'environnement Cecil.

Description:
  Diagnoses the site configuration

Usage:
  doctor [options] [--] [<path>]

Arguments:
  path                       Use the given path as working directory

Options:
  -c, --config=CONFIG        Set the path to an extra configuration file
  -h, --help                 Display help for the given command. When no command is given display help for the list command
  -q, --quiet                Do not output any message
  -V, --version              Display this application version
      --ansi|--no-ansi       Force (or disable --no-ansi) ANSI output
  -n, --no-interaction       Do not ask any interactive question
  -v|vv|vvv, --verbose       Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The doctor command diagnoses the current site and Cecil environment.

    cecil.phar doctor
    cecil.phar doctor path/to/the/working/directory

  To inspect a site with an extra configuration file, run:

    cecil.phar doctor --config=config.yml

doctor:frontmatter

Valide la syntaxe du front matter des pages.

Description:
  Validates pages front matter syntax

Usage:
  doctor:frontmatter|doctor:fm [options] [--] [<path>]

Arguments:
  path                  Use the given path as working directory

Options:
  -c, --config=CONFIG   Set the path to an extra configuration file
  -p, --page=PAGE       Validate a single page relative to the pages directory
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
  -v|vv|vvv             Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

doctor:seo

Audite les pages HTML rendues pour détecter les problèmes SEO courants.

Description:
  Audits rendered HTML pages for common SEO issues

Usage:
  doctor:seo [options] [--] [<path>]

Arguments:
  path                  Use the given path as working directory

Options:
  -c, --config=CONFIG   Set the path to an extra configuration file
  -p, --page=PAGE       Audit a single page relative to the pages directory
      --format=FORMAT   Output format: text (default) or json
      --feedback        Include findings with feedback level
      --include-virtual Include virtual pages (paginated, taxonomies) in audit

La commande construit le site en mode dry-run, puis audite le HTML rendu avec un jeu de contrôles ciblés : balise title, meta description, URL canonique, structure des titres, balises Open Graph, attributs alt des images et longueur estimée du contenu.

Par défaut, les pages virtuelles (paginées, pages de taxonomie) sont exclues de l'audit. Utilisez --include-virtual pour les inclure.

Par défaut, les findings de niveau feedback ne sont pas listés.

Utilisez --feedback pour inclure les findings de niveau feedback en plus des autres findings.

Exportez les résultats en JSON pour l'intégration CI en utilisant --format=json.

Configuration

Personnalisez les seuils d'audit et les contrôles activés dans votre fichier de configuration :

doctor:
  seo:
    title: { min: 30, max: 60 }
    description: { min: 120, max: 160 }
    content: { min_words: 300 }
    checks:
      title: true
      description: true
      canonical: true
      h1: true
      og_tags: true
      img_alt: true
      content_length: true
      lang_attribute: true

Données

Emplacement des fichiers de données et types d’extensions pris en charge.

Formats pris en charge : YAML, JSON, XML et CSV.

data.dir

Répertoire source des données (data par défaut).

data:
  dir: data

data.ext

Tableau des extensions de fichiers.

data:
  ext: [yaml, yml, json, xml, csv]

data.load

Active la collection site.data (true par défaut).

data:
  load: true

Fichiers statiques

Gestion des fichiers statiques copiés (PDF, polices, etc.).

static.dir

Répertoire source des fichiers statiques (static par défaut).

static:
  dir: static

static.target

Répertoire vers lequel les fichiers statiques sont copiés (root par défaut).

static:
  target: ''

static.exclude

Liste des fichiers exclus. Accepte les glob, les chaînes et les expressions régulières.

static:
  exclude: ['sass', 'scss', '*.scss', 'package*.json', 'node_modules']

static.load

Active la collection site.static (false par défaut).

static:
  load: false

static.mounts

Permet de copier des fichiers ou répertoires spécifiques vers une destination spécifique.

static:
  mounts: []

exemple de static

static:
  dir: docs
  target: docs
  exclude: ['sass', '*.scss', '/\.bck$/']
  load: true
  mounts:
    - source/path/file.ext: dest/path/file.ext
    - node_modules/bootstrap-icons/font/fonts: fonts

Vous pouvez créer du contenu dynamique dans une page en utilisant la fonction Twig template_from_string.

{{ include(template_from_string(page.content, "contenu dynamique pour la page " ~ page.id)) }}

Avec cette approche, vous pouvez utiliser n’importe quelle variable de page dans le body de la page.

--
var: 'value'
---
La valeur de `var` est {{ page.var }}.

Gestion des ressources (images, fichiers CSS et JS).

assets.dir

Répertoire source des ressources (assets par défaut).

assets:
  dir: assets

assets.target

Répertoire où les fichiers de ressources distants et redimensionnés sont enregistrés (root par défaut).

assets:
  target: ''

assets.fingerprint

Active le fingerprinting (cache busting) pour les fichiers de ressources (true par défaut).

assets:
  fingerprint: true

assets.compile

Active la compilation des fichiers Sass (true par défaut). Voir la documentation de scssphp pour les détails des options.

assets:
  compile:
    style: expanded      # style de compilation (`expanded` ou `compressed`, `expanded` par défaut)
    import: [sass, scss] # liste des chemins importés (`[sass, scss, node_modules]` par défaut)
    sourcemap: false     # active les sourcemaps en mode debug (`false` par défaut)
    variables: []        # liste de variables préconfigurées (vide par défaut)

assets.minify

Active la minification CSS et JS (true par défaut).

assets:
  minify: true

assets.images

Gestion des images.

assets:
  images:
    optimize: false # active l’optimisation d’images avec JpegOptim, Optipng, Pngquant 2, SVGO 1, Gifsicle, cwebp, avifenc (`false` par défaut)
    quality: 75     # qualité d’image pour `optimize` et `resize` (`75` par défaut)
    responsive:
      widths: [480, 640, 768, 1024, 1366, 1600, 1920] # largeurs d’image pour l’attribut `srcset`
      sizes:
        default: '100vw' # attribut `sizes` par défaut (`100vw` par défaut)

assets.images.cdn

L’URL des ressources image peut être facilement remplacée par une url de CDN fournie.

assets:
  images:
    cdn:
      enabled: false  # active Image CDN (`false` par défaut)
      canonical: true # `image_url` est canonique (au lieu d’un chemin relatif) (`true` par défaut)
      remote: true    # prend aussi en charge les images non locales (`true` par défaut)
      account: 'xxxx' # compte du fournisseur
      url: 'https://provider.tld/%account%/%image_url%?w=%width%&q=%quality%&format=%format%'

url est un modèle qui contient des variables :

• %account% remplacé par l’option assets.images.cdn.account
• %image_url% remplacé par l’URL canonique de l’image ou par path
• %width% remplacé par la largeur de l’image
• %quality% remplacé par l’option assets.images.quality
• %format% remplacé par le format de l’image

Voir les fournisseurs CDN.

assets.remote.useragent

User agent utilisé pour télécharger les ressources distantes.

assets:
  remote:
    useragent:
      default: <string> # user agent par défaut
      useragent1: <string>
      useragent2: <string>

Options des templates.

layouts.dir

Répertoire source des templates (layouts par défaut).

layouts:
  dir: layouts

layouts.autoescape

Surcharge l’option Twig autoescape (false par défaut).

Si la valeur est null, Cecil applique une stratégie basée sur l’extension du nom de template :

• *.js.twig -> js
• *.css.twig -> css
• *.html.twig et *.twig -> html
• toute autre extension -> false

layouts:
  autoescape: false  # désactive l’échappement automatique (par défaut)
  #autoescape: null  # utilise la stratégie automatique Cecil selon l’extension du template
  #autoescape: html
  #autoescape: js

layouts.images

Options de gestion des images.

layouts:
  images:
    formats: []       # utilisé par la fonction `html` : ajoute des formats d’image alternatifs comme `source` (ex. `[avif, webp]`, tableau vide par défaut)
    responsive: false # utilisé par la fonction `html` : ajoute des images responsives ('width' ou 'density', `false` par défaut)
    placeholder: ''   # utilisé par la fonction `html` : remplit l’arrière-plan de l’image avant son chargement (`color` ou `lqip`, désactivé par défaut)
    dark_suffix: ''   # suffixe de l’image variante sombre (ex. `.dark`), désactivé par défaut
    mobile_suffix: '' # suffixe de l’image variante mobile (ex. `.mobile`), désactivé par défaut
    mobile_media_query: '(max-width: 767px)' # media query de la `<source>` de la variante mobile

layouts.translations

Options de gestion des traductions.

layouts:
  translations:
    dir: translations # répertoire source des traductions (`translations` par défaut)
    formats:          # formats de traduction pris en charge
      yaml:
        loader: Symfony\Component\Translation\Loader\YamlFileLoader
        ext: [yml, yaml]
      mo:
        loader: Symfony\Component\Translation\Loader\MoFileLoader
        ext: [mo]

Chaque format de traduction définit :

• loader : classe du chargeur de traduction Symfony
• ext : une ou plusieurs extensions de fichier associées à ce format

layouts.components

Options des composants de template.

layouts:
  components:
    dir: components # répertoire source des composants (`components` par défaut)
    ext: twig       # extension des fichiers de composants (`twig` par défaut)

layouts.sections

Associe une section aux layouts d’une autre section : le nom associé est utilisé à la place de <section> par les règles de recherche de la section et de ses pages.

layouts:
  sections:
    news: blog # la section « news » est rendue avec `blog/list.html.twig` et ses pages avec `blog/page.html.twig`

Définit où et dans quel format les pages sont rendues.

output.dir

Répertoire où les fichiers de pages rendues sont enregistrés (_site par défaut).

output:
  dir: _site

output.formats

Liste de définition des formats de sortie, utilisés pour rendre les pages (par ex. HTML, Atom, RSS, JSON, XML, etc.).

output:
  formats:
    - name: <name>            # nom du format, par ex. `html` (requis)
      mediatype: <media type> # type MIME, ex. `text/html` (facultatif)
      subpath: <sub path>     # sous-chemin, ex. `amp` dans `path/amp/index.html` (facultatif)
      filename: <file name>   # nom du fichier, ex. `index` dans `path/index.html` (facultatif)
      extension: <extension>  # extension du fichier, ex. `html` dans `path/index.html` (requis)
      exclude: [<variable>]   # n’applique pas ce format aux pages identifiées par les variables listées, ex. `[redirect, paginated]` (facultatif)

Ces formats sont utilisés dans la configuration output.pagetypeformats et dans la variable de page output.

Formats par défaut

Cecil fournit quelques formats par défaut, qui peuvent être surchargés dans le fichier de configuration : html (par défaut), atom, rss, json, xml, txt, amp, js, webmanifest, xsl, jsonfeed, iframe, oembed.

output.pagetypeformats

Il n’est pas nécessaire de définir la variable output pour chaque page, car Cecil applique automatiquement les formats définis pour chaque type de page (homepage, page, section, vocabulary et term).

output:
  pagetypeformats:
    page: [<format>]
    homepage: [<format>]
    section: [<format>]
    vocabulary: [<format>]
    term: [<format>]

Plusieurs formats peuvent être définis pour un même type de page. Par exemple, le type de page section peut être rendu automatiquement en HTML et Atom :

output:
  pagetypeformats:
    section: [html, atom]

exemple de output

output:
  dir: _site
  formats:
    - name: html
      mediatype: text/html
      filename: index
      extension: html
    - name: atom
      mediatype: application/xml
      filename: atom
      extension: xml
      exclude: [redirect, paginated]
  pagetypeformats:
    page: [html]
    homepage: [html, atom]
    section: [html, atom]
    vocabulary: [html]
    term: [html, atom]

Post-process

Vous pouvez étendre les capacités de Cecil avec un post-processeur de sortie pour modifier les fichiers de sortie après leur génération.

Options de cache.

cache.enabled

Le cache est activé par défaut (true), mais vous pouvez le désactiver avec :

cache:
  enabled: false

cache.dir

Répertoire où les fichiers de cache sont stockés (.cache par défaut).

cache:
  dir: '.cache'

cache.assets

Options du cache des ressources.

cache.assets.ttl

Temps de vie du cache des ressources en secondes (null par défaut = aucune expiration).

cache:
  assets:
    ttl: ~

cache.assets.remote.ttl

Temps de vie du cache des ressources distantes en secondes (7 jours par défaut).

cache:
  assets:
    remotes:
      ttl: 604800 # 7 jours

cache.templates

Désactive le cache des templates avec false (true par défaut).

cache:
  templates: true

cache.translations

Désactive le cache des traductions avec false (true par défaut).

cache:
  translations: true

Serveur

server.headers

Vous pouvez définir des en-têtes HTTP personnalisés, utilisés par le serveur d’aperçu local.

server:
  headers:
    - path: <path> # chemin relatif, préfixé par un slash. Prend en charge le joker "*".
      headers:
        - key: <key>
          value: "<value>"

Exemple :

server:
  headers:
    - path: /*
      headers:
        - key: X-Frame-Options
          value: "SAMEORIGIN"
        - key: X-XSS-Protection
          value: "1; mode=block"
        - key: X-Content-Type-Options
          value: "nosniff"
        - key: Content-Security-Policy
          value: "default-src 'self'; object-src 'self'; img-src 'self'"
        - key: Strict-Transport-Security
          value: "max-age=31536000; includeSubDomains; preload"
    - path: /assets/*
      headers:
        - key: Cache-Control
          value: "public, max-age=31536000"
    - path: /foo.html
      headers:
        - key: Foo
          value: "bar"

Optimisation

Les options d’optimisation permettent d’activer la compression des fichiers de sortie : HTML, CSS, JavaScript et images.

optimize:
  enabled: false     # active l’optimisation des fichiers (`false` par défaut)
  html:
    enabled: true    # active l’optimisation des fichiers HTML
    ext: [html, htm]   # extensions de fichiers prises en charge
  css:
    enabled: true    # active l’optimisation des fichiers CSS
    ext: [css]         # extensions de fichiers prises en charge
  js:
    enabled: true    # active l’optimisation des fichiers JavaScript
    ext: [js]          # extensions de fichiers prises en charge
  images:
    enabled: true    # active l’optimisation des fichiers images
    ext: [jpeg, jpg, png, gif, webp, svg, avif] # extensions de fichiers prises en charge

Cette option est désactivée par défaut et peut être activée via :

optimize: true

Une fois l’option globale activée, les 4 types de fichiers seront traités.
Il est possible de désactiver chacun d’eux via enabled: false et de modifier l’extension des fichiers traités via ext.

Variables d’environnement

La configuration peut être surchargée via des variables d’environnement.

Au démarrage, Cecil essaie également de charger un fichier .env depuis le chemin du site courant (le répertoire de travail actuel, ou l’argument <path> s’il est fourni).

• Si le fichier .env n’existe pas, Cecil continue normalement.
• Les variables déjà définies par le shell/système sont conservées.

Chaque nom de variable d’environnement doit être préfixé par CECIL_ et la clé de configuration doit être en majuscules.

Par exemple, la commande suivante définit le baseurl du site :

export CECIL_BASEURL="https://example.com/"

Vous pouvez stocker la même valeur dans un fichier .env à la racine du projet :

CECIL_BASEURL="https://example.com/"
CECIL_TITLE="Mon site Cecil"

Option CLI

Vous pouvez combiner plusieurs fichiers de configuration avec l’option --config (priorité de gauche à droite) :

php cecil.phar --config config-1.yml,config-2.yml

Exemples de configuration de fournisseurs de CDN pour les options de configuration.

Cloudinary

https://cloudinary.com

assets:
  images:
    cdn:
      enabled: true
      account: 'xxxx'
      url: 'https://res.cloudinary.com/%account%/image/fetch/c_limit,w_%width%,q_%quality%,f_%format%,d_default/%image_url%'

Cloudimage

https://www.cloudimage.io

assets:
  images:
    cdn:
      enabled: true
      account: 'xxxx'
      url: 'https://%account%.cloudimg.io/%image_url%?w=%width%&q=%quality%&force_format=%format%'

TwicPics

https://www.twicpics.com

assets:
  images:
    cdn:
      enabled: true
      account: 'xxxx'
      canonical: false
      remote: false
      url: 'https://%account%.twic.pics/%image_url%?twic=v1/resize=%width%/quality=%quality%/output=%format%'

Source URL : URL de base de votre site.

imgix

https://imgix.com

assets:
  images:
    cdn:
      enabled: true
      account: 'xxxx'
      canonical: false
      remote: false
      url: 'https://%account%.imgix.net/%image_url%?w=%width%&q=%quality%&fm=%format%'

Base URL : URL de base de votre site.

Netlify Image CDN

https://docs.netlify.com/image-cdn/overview/

assets:
  images:
    cdn:
      enabled: true
      canonical: false
      url: '/.netlify/images?url=%image_url%&w=%width%&fm=%format%'

Exécution en local

Installer Netlify CLI

npm install netlify-cli -g
netlify link

netlify.toml :

[dev]
  targetPort = 8000

Démarrer le serveur local

php cecil.phar serve & netlify dev

Ouvrez http://localhost:8888

Créer un site web

Vous pouvez créer un nouveau site web en quelques minutes.

Suivez les étapes ci-dessous pour créer votre premier site web Cecil.

Prérequis

• PHP 8.3+
• Terminal (une compréhension de base du terminal)
• Éditeur de texte, comme VS Code et/ou Typora

1. Télécharger Cecil

Téléchargez cecil.phar depuis votre terminal:

curl -LO https://cecil.app/cecil.phar

Vous pouvez également télécharger Cecil manuellement, ou utiliser :

• Homebrew: brew install cecilapp/tap/cecil
• Scoop: scoop install https://cecil.app/scoop/cecil.json

2. Créer un nouveau site

Créez un répertoire pour le site Web (ex : <monsiteweb>), placez y cecil.phar, puis exécutez la commande new:site :

php cecil.phar new:site

3. Ajouter une page

Exécutez la commande new:page :

php cecil.phar new:page

Vous pouvez maintenant modifier la page nouvellement créée avec votre éditeur Markdown : <monsiteweb>/pages/<nouvelle-page>.md.

4. Vérifier l’aperçu

Exécutez la commande suivante pour créer un aperçu du site Web :

php cecil.phar serve

Naviguez ensuite sur http://localhost:8000.

5. Générer et déployer

Quand vous êtes satisfait du résultat, vous pouvez générer le site afin de le déployer sur le Web.

Exécutez la commande suivante pour générer le site :

php cecil.phar build

Vous pouvez maintenant copier le contenu du répertoire _site sur un serveur Web 🎉

Pour démarrer rapidement, utilisez l’un des kits de démarrage Cecil prêts à l’emploi :

• The Butler : starter blog prêt à publier.
• Links : alternative open source à Linktree.
• Photo Stream : flux photo auto-hébergé minimaliste.
• Statidocs : site de documentation prêt à l’emploi.

Codes de locale disponibles (language_COUNTRY) utilisés par l’option languages.