Logo de Cecil Cecil
Sur cette page

Étendre Cecil

Comme Cecil est écrit en PHP, il est facile d’en étendre les capacités.

Chargement automatique

Les classes personnalisées sont chargées automatiquement depuis le répertoire extensions de votre site (ou d’un thème), le chemin du fichier correspondant à l’espace de noms : la classe MySite\Generator\MyGenerator est chargée depuis extensions/MySite/Generator/MyGenerator.php.

Pour utiliser une autre organisation, déclarez des correspondances PSR-4, relatives au répertoire du site (ou du thème) :

extensions:
  autoload:
    'MySite\': src/ # `MySite\Generator\MyGenerator` est chargée depuis `src/Generator/MyGenerator.php`

Si vos extensions dépendent de bibliothèques tierces, installez-les avec Composer dans le répertoire extensions (composer require <paquet> --working-dir=extensions) : extensions/vendor/autoload.php est chargé automatiquement, y compris avec le phar de Cecil. Les bibliothèques déjà fournies par Cecil ne sont pas remplacées.

Configuration

Les générateurs de pages, les extensions Twig, les post-processeurs de sortie, les abonnés aux événements de build et les plugins se déclarent de la même façon, sous forme de liste indexée par nom :

<clé>:
  <nom>: <classe>                                         # priorité par défaut (100)
  <nom>: { class: <classe>, priority: <int> }             # priorité explicite
  <nom>: false                                            # désactivé
  • Les extensions sont exécutées par ordre croissant de priorité ; sans priorité, elles sont exécutées après les extensions intégrées (priorité 100), dans leur ordre de déclaration.
  • Une extension intégrée peut être désactivée (Redirect: false) ou déplacée (Section: { priority: 45 }) par son nom.
  • Une extension qui ne peut pas être chargée (classe inconnue, mauvaise interface, option invalide) est ignorée et l’erreur est journalisée. Pour faire échouer le build à la place, activez le mode strict (false journalise seulement l’erreur, sans l’avertissement concernant Cecil 10) :
extensions:
  strict: true

Générateurs 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 une nouvelle classe PHP héritant de Cecil\Generator\AbstractGenerator, puis ajoutez-la à la liste pages.generators.

Les générateurs intégrés utilisent les priorités 10 à 90 : choisissez la priorité de votre générateur selon les pages dont il a besoin (par ex. après Section pour accéder aux pages de sections).

Un générateur ajoute des pages à $this->generatedPages (une page ayant l’ID d’une page existante la remplace), et peut supprimer des pages existantes avec $this->removePage('<id-de-page>').

Exemple :

/extensions/MySite/Generator/DummyPage.php

<?php
namespace MySite\Generator;

use Cecil\Collection\Page\Page;
use Cecil\Collection\Page\Type;
use Cecil\Generator\AbstractGenerator;
use Cecil\Generator\GeneratorInterface;

class DummyPage extends AbstractGenerator implements GeneratorInterface
{
    public function generate(): void
    {
        // crée une nouvelle page $page, puis l’ajoute à la collection du site
        $page = (new Page('my-page'))
            ->setType(Type::PAGE)
            ->setPath('mypage')
            ->setBodyHtml('<p>My page body</p>')
            ->setVariable('language', 'en')
            ->setVariable('title', 'My page')
            ->setVariable('date', new \DateTime())
            ->setVariable('menu', ['main' => ['weight' => 99]]);
        $this->generatedPages->add($page);
    }
}

/extensions/MySite/Generator/Database.php

<?php
namespace MySite\Generator;

use Cecil\Collection\Page\Page;
use Cecil\Collection\Page\Type;
use Cecil\Generator\AbstractGenerator;
use Cecil\Generator\GeneratorInterface;

class Database extends AbstractGenerator implements GeneratorInterface
{
    public function generate(): void
    {
        // crée des pages à partir d’une base de données SQLite
        $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)
                ->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:
    DummyPage: MySite\Generator\DummyPage
    Database: { class: MySite\Generator\Database, priority: 35 }

Extension Twig

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

  1. créez une extension Twig
  2. ajoutez le fichier PHP dans le répertoire extensions (voir Chargement automatique)
  3. ajoutez-la à la configuration layouts.extensions

Le constructeur de l’extension reçoit l’instance de Cecil\Builder, qui donne accès à la configuration et au contenu du site.

Exemple :

/extensions/MySite/Twig/MyTwigExtension.php

<?php
namespace MySite\Twig;

class MyTwigExtension extends \Twig\Extension\AbstractExtension
{
    public function getFilters(): array
    {
        // ajoute un nouveau filtre nommé 'md5'
        return [
            new \Twig\TwigFilter('md5', 'md5'),
        ];
    }
}

configuration

layouts:
  extensions:
    MyExtension: MySite\Twig\MyTwigExtension

Post-processeurs de sortie

Vous pouvez post-traiter le rendu des pages.

Créez une nouvelle classe PHP héritant de Cecil\Renderer\PostProcessor\AbstractPostProcessor, puis ajoutez-la à la liste output.postprocessors.

Les post-processeurs intégrés (GeneratorMetaTag, HtmlExcerpt et MarkdownLink) utilisent les priorités 10 à 30 : ils sont donc exécutés en premier par défaut.

Exemple :

/extensions/MySite/PostProcessor/MyProcessor.php

<?php
namespace MySite\PostProcessor;

use Cecil\Collection\Page\Page;
use Cecil\Renderer\PostProcessor\AbstractPostProcessor;

class MyProcessor extends AbstractPostProcessor
{
    public function process(Page $page, string $output, string $format): string
    {
        // ajoute une balise meta dans le head de la sortie HTML
        if ($format == 'html') {
            if (!preg_match('/<meta name="test".*/i', $output)) {
                $meta = '<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: MySite\PostProcessor\MyProcessor

Convertisseur Markdown

Le front matter et le corps Markdown des pages sont convertis par la classe définie dans pages.converter. Elle est aussi utilisée par le filtre markdown_to_html et pour les pages externes (le filtre toc utilise directement l’analyseur Markdown).

Pour modifier la conversion, créez une classe PHP implémentant Cecil\Converter\ConverterInterface (son constructeur reçoit l’instance de Cecil\Builder), ou héritant de la classe par défaut Cecil\Converter\Converter.

Exemple :

/extensions/MySite/Converter.php

<?php
namespace MySite;

class Converter extends \Cecil\Converter\Converter
{
    public function convertBody(string $string, ?string $language = null): string
    {
        // remplace `[[page-id]]` par un lien, avant la conversion par défaut
        $string = preg_replace('/\[\[([a-z0-9-\/]+)\]\]/', '[$1]($1.md)', $string);

        return parent::convertBody($string, $language);
    }
}

configuration

pages:
  converter: MySite\Converter

Analyseur Markdown

Pour ajouter votre propre syntaxe Markdown, remplacez l’analyseur Markdown utilisé par le convertisseur par défaut (et par les filtres markdown_to_html et toc) avec l’option pages.body.parser.

Créez une classe PHP héritant de Cecil\Converter\Parsedown, basée sur Parsedown (1.x) et Parsedown Extra, et déclarez votre syntaxe avec son mécanisme d’extension : un caractère déclencheur dans $this->InlineTypes (ou $this->BlockTypes) fait référence à une méthode inline<Type>() (ou aux méthodes block<Type>(), block<Type>Continue() et block<Type>Complete()).

L’analyseur peut aussi être créé en dehors d’une génération (voir Bibliothèque) : transmettez les options au constructeur parent, et ne dépendez pas de l’état d’une génération (par exemple la collection des pages).

Exemple :

/extensions/MySite/Parsedown.php

<?php
namespace MySite;

use Cecil\Builder;

class Parsedown extends \Cecil\Converter\Parsedown
{
    public function __construct(Builder $builder, ?array $options = null)
    {
        parent::__construct($builder, $options);
        // `==texte==` → `<mark>texte</mark>`
        $this->InlineTypes['='][] = 'Mark';
        $this->inlineMarkerList .= '=';
    }

    protected function inlineMark($Excerpt)
    {
        if (preg_match('/^==(?=\S)(.+?)(?<=\S)==/', $Excerpt['text'], $matches)) {
            return [
                'extent'  => \strlen($matches[0]),
                'element' => ['name' => 'mark', 'text' => $matches[1], 'handler' => 'line'],
            ];
        }

        return null;
    }
}

configuration

pages:
  body:
    parser: MySite\Parsedown

Événements de build

Des événements sont déclenchés pendant le build : écoutez-les pour exécuter votre propre code avant ou après le build, chaque étape, ou à chaque étape du cycle de vie d’une page (par ex. pour créer un index de recherche, notifier un service ou modifier la sortie des pages).

Événement Constante Quand Classe d’événement
build.start BuildEvents::BUILD_START avant la première étape BuildEvent
build.finished BuildEvents::BUILD_FINISHED après la dernière étape BuildEvent
step.pre BuildEvents::STEP_PRE avant chaque étape StepEvent
step.post BuildEvents::STEP_POST après chaque étape StepEvent
page.created BuildEvents::PAGE_CREATED après la création d’une page à partir d’un fichier de contenu PageEvent
page.converted BuildEvents::PAGE_CONVERTED après la conversion d’une page publiée (front matter et corps) PageEvent
page.rendered BuildEvents::PAGE_RENDERED après le rendu d’une page dans un format (après post-processeurs) PageRenderedEvent
page.saved BuildEvents::PAGE_SAVED après l’enregistrement d’une page rendue dans un fichier PageSavedEvent

Chaque événement donne accès au contexte du build (getBuilder()) et à ses options (getOptions()) ; StepEvent ajoute getStep(), PageEvent ajoute getPage(), PageRenderedEvent ajoute getFormat(), getOutput() et setOutput(), PageSavedEvent ajoute getFormat() et getPathname().

Créez un abonné aux événements héritant de Cecil\Event\AbstractSubscriber (qui donne accès à $this->builder et $this->config), puis ajoutez-le à la liste extensions.subscribers.

Exemple :

/extensions/MySite/SearchIndex.php

<?php
namespace MySite;

use Cecil\Event\AbstractSubscriber;
use Cecil\Event\BuildEvent;
use Cecil\Event\BuildEvents;
use Cecil\Event\PageEvent;

class SearchIndex extends AbstractSubscriber
{
    private array $index = [];

    public static function getSubscribedEvents(): array
    {
        return [
            BuildEvents::PAGE_CONVERTED => 'onPageConverted',
            BuildEvents::BUILD_FINISHED => 'onBuildFinished',
        ];
    }

    public function onPageConverted(PageEvent $event): void
    {
        $page = $event->getPage();
        $this->index[] = ['title' => $page->getVariable('title'), 'path' => $page->getPath()];
    }

    public function onBuildFinished(BuildEvent $event): void
    {
        if ($event->getOptions()['dry-run']) {
            return;
        }
        file_put_contents($this->config->getOutputPath() . '/search.json', json_encode($this->index));
    }
}

configuration

extensions:
  subscribers:
    SearchIndex: MySite\SearchIndex

Plugins

Un plugin est un point d’entrée unique qui enregistre un ensemble d’extensions : générateurs, extensions Twig, post-processeurs, abonnés et écouteurs d’événements, et configuration par défaut. C’est la façon recommandée de fournir des extensions avec un thème : activer le thème active son plugin, sans autre configuration.

Créez une classe PHP héritant de Cecil\Plugin\AbstractPlugin (qui donne accès à $this->builder et $this->config), puis ajoutez-la à la liste extensions.plugins.

Exemple :

/themes/example/extensions/Example/ExamplePlugin.php

<?php
namespace Example;

use Cecil\Event\BuildEvents;
use Cecil\Plugin\AbstractPlugin;
use Cecil\Plugin\Registry;

class ExamplePlugin extends AbstractPlugin
{
    public function register(Registry $registry): void
    {
        $registry
            ->config(['example' => ['feed' => ['limit' => 10]]]) // options par défaut
            ->twigExtension(Twig\ExampleExtension::class)
            ->generator(Generator\Feed::class, priority: 35)
            ->postProcessor(PostProcessor\Minify::class)
            ->subscriber(SearchIndex::class)
            ->listen(BuildEvents::BUILD_FINISHED, fn () => $this->builder->getLogger()->notice('Example is ready'));
    }
}

/themes/example/config.yml

extensions:
  plugins:
    Example: Example\ExamplePlugin

Les extensions enregistrées par un plugin sont nommées d’après le nom court de leur classe (par ex. Feed), sauf si un name est fourni, et utilisent la priorité par défaut (100), sauf si une priority est fournie. La configuration du plugin a la priorité la plus faible : la configuration du site (et des thèmes) peut remplacer ses options, et désactiver (Feed: false) ou déplacer (Feed: { priority: 45 }) ses extensions par leur nom.