What's on this page
Extend Cecil
Because Cecil is written in PHP, it's easy to extend its capabilities.
Autoloading
Custom classes are autoloaded from the extensions directory of your site (or of a theme), the file path matching the namespace: the class MySite\Generator\MyGenerator is loaded from extensions/MySite/Generator/MyGenerator.php.
To use another layout, declare PSR-4 mappings, relative to the site (or theme) directory:
extensions:
autoload:
'MySite\': src/ # `MySite\Generator\MyGenerator` is loaded from `src/Generator/MyGenerator.php`
If your extensions depend on third-party libraries, install them with Composer in the extensions directory (composer require <package> --working-dir=extensions): extensions/vendor/autoload.php is loaded automatically, even with the Cecil phar. Libraries already provided by Cecil are not overridden.
Configuration
Page generators, Twig extensions, output post-processors, build events subscribers and plugins are declared the same way, as a map indexed by name:
<key>:
<name>: <class> # default priority (100)
<name>: { class: <class>, priority: <int> } # explicit priority
<name>: false # disabled
- Extensions run in ascending order of their priority; without a priority, they run after the built-in ones (priority
100), in their declaration order. - A built-in extension can be disabled (
Redirect: false) or moved (Section: { priority: 45 }) by its name. - An extension that cannot be loaded (unknown class, wrong interface, invalid option) is skipped and the error is logged. To fail the build instead, enable the strict mode (
falseonly logs the error, without the Cecil 10 warning):
extensions:
strict: true
Page generators
A generator helps you create pages without Markdown files (for example, with data from an API or a database) or alter existing pages.
Create a new PHP class extending Cecil\Generator\AbstractGenerator, and add it to the pages.generators list.
Built-in generators use the priorities 10 to 90: choose the priority of your generator depending on the pages it needs (e.g.: after Section to access sections pages).
A generator adds pages to $this->generatedPages (a page with the ID of an existing page replaces it), and can remove existing pages with $this->removePage('<page-id>').
Example:
/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
{
// create a new page $page, then add it to the site collection
$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
{
// 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)
->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 }
Twig extension
You can add custom functions and filters:
- create a Twig extension
- add the PHP file in the
extensionsdirectory (see Autoloading) - add it to the
layouts.extensionsconfiguration
The extension constructor receives the Cecil\Builder instance, which gives access to the configuration and the site content.
Example:
/extensions/MySite/Twig/MyTwigExtension.php
<?php
namespace MySite\Twig;
class MyTwigExtension extends \Twig\Extension\AbstractExtension
{
public function getFilters(): array
{
// add a new filter named 'md5'
return [
new \Twig\TwigFilter('md5', 'md5'),
];
}
}
configuration
layouts:
extensions:
MyExtension: MySite\Twig\MyTwigExtension
Output post-processors
You can post-process the rendered output of pages.
Create a new PHP class extending Cecil\Renderer\PostProcessor\AbstractPostProcessor, and add it to the output.postprocessors list.
Built-in post-processors (GeneratorMetaTag, HtmlExcerpt and MarkdownLink) use the priorities 10 to 30, so they run first by default.
Example:
/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
{
// add a meta tag to the head of the HTML output
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
Markdown converter
The front matter and the Markdown body of pages are converted by the class defined in pages.converter. It is also used by the markdown_to_html filter and for external pages (the toc filter uses the Markdown parser directly).
To change the conversion, create a PHP class implementing Cecil\Converter\ConverterInterface (its constructor receives the Cecil\Builder instance), or extending the default Cecil\Converter\Converter class.
Example:
/extensions/MySite/Converter.php
<?php
namespace MySite;
class Converter extends \Cecil\Converter\Converter
{
public function convertBody(string $string, ?string $language = null): string
{
// replaces `[[page-id]]` with a link, before the default conversion
$string = preg_replace('/\[\[([a-z0-9-\/]+)\]\]/', '[$1]($1.md)', $string);
return parent::convertBody($string, $language);
}
}
configuration
pages:
converter: MySite\Converter
Markdown parser
To add your own Markdown syntax, replace the Markdown parser used by the default converter (and by the markdown_to_html and toc filters) with the pages.body.parser option.
Create a PHP class extending Cecil\Converter\Parsedown, based on Parsedown (1.x) and Parsedown Extra, and register your syntax with its extension mechanism: a marker character in $this->InlineTypes (or $this->BlockTypes) refers to an inline<Type>() method (or block<Type>(), block<Type>Continue() and block<Type>Complete() methods).
The parser can also be created outside of a build (see Library): pass the options to the parent constructor, and do not rely on the state of a build (e.g. the pages collection).
Example:
/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);
// `==text==` → `<mark>text</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
Build events
Events are dispatched during the build: listen to them to run your own code before or after the build, each step, or at each step of the life cycle of a page (e.g.: to create a search index, notify a service, or modify the output of pages).
| Event | Constant | When | Event class |
|---|---|---|---|
build.start |
BuildEvents::BUILD_START |
before the first step | BuildEvent |
build.finished |
BuildEvents::BUILD_FINISHED |
after the last step | BuildEvent |
step.pre |
BuildEvents::STEP_PRE |
before each step | StepEvent |
step.post |
BuildEvents::STEP_POST |
after each step | StepEvent |
page.created |
BuildEvents::PAGE_CREATED |
after a page is created from a content file | PageEvent |
page.converted |
BuildEvents::PAGE_CONVERTED |
after a published page is converted (front matter and body) | PageEvent |
page.rendered |
BuildEvents::PAGE_RENDERED |
after a page is rendered in a format (after post-processors) | PageRenderedEvent |
page.saved |
BuildEvents::PAGE_SAVED |
after a rendered page is saved to a file | PageSavedEvent |
Every event gives access to the build context (getBuilder()) and options (getOptions()); StepEvent adds getStep(), PageEvent adds getPage(), PageRenderedEvent adds getFormat(), getOutput() and setOutput(), PageSavedEvent adds getFormat() and getPathname().
Create an event subscriber extending Cecil\Event\AbstractSubscriber (which gives access to $this->builder and $this->config), and add it to the extensions.subscribers list.
Example:
/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
A plugin is a single entry point that registers a set of extensions: generators, Twig extensions, post-processors, event subscribers and listeners, and default configuration. It's the recommended way to ship extensions with a theme: enabling the theme enables its plugin, with no other configuration.
Create a PHP class extending Cecil\Plugin\AbstractPlugin (which gives access to $this->builder and $this->config), and add it to the extensions.plugins list.
Example:
/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]]]) // default options
->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
Extensions registered by a plugin are named after their short class name (e.g.: Feed), unless a name is given, and use the default priority (100) unless a priority is given. The plugin configuration has the lowest precedence: the site (and themes) configuration can override its options, and disable (Feed: false) or move (Feed: { priority: 45 }) its extensions by name.