{ "version": "https://jsonfeed.org/version/1.1", "title": "Cecil - Developers", "home_page_url": "https://cecil.app/documentation/developers/", "feed_url": "https://cecil.app/documentation/developers/feed.json", "description": "Extend Cecil with PHP, use it as a library and understand its architecture.", "icon": "https://cecil.app/favicon.7ff4b89eec6dad139a7d2d6561543285.png", "favicon": "https://cecil.app/thumbnails/64x/favicon.7ff4b89eec6dad139a7d2d6561543285.png", "language": "en", "items": [ { "id": "https://cecil.app/documentation/developers/architecture/", "url": "https://cecil.app/documentation/developers/architecture/", "title": "Architecture", "summary": "Diagram of the build pipeline and key components.", "date_published": "2026-05-27T00:00:00+00:00", "date_modified": "2026-10-02T00:00:00+00:00","content_text": "Architecture\nDiagram\ngraph TD\n %% Entry\n CLI[\"bin\/cecil\\n(CLI entry point)\"]\n APP[\"Application\\n(Symfony Console)\"]\n CMD[\"Commands\\nbuild \/ serve \/ new:site\\nnew:page \/ clear \/ show:content\"]\n\n CLI --> APP --> CMD\n\n %% Orchestrator\n BUILDER[\"Builder\\n(Orchestrator)\"]\n CONFIG[\"Configuration\\n(config.yml + default.php\\n+ themes)\"]\n CMD --> BUILDER\n CONFIG --> BUILDER\n\n %% Pipeline\n subgraph PIPELINE[\"Build pipeline (steps)\"]\n S1[\"1. Pages\/Load\\n(Finder -> Markdown files)\"]\n S2[\"2. Data\/Load\\n(YAML files)\"]\n S3[\"3. StaticFiles\/Load\\n(load static files)\"]\n S4[\"4. Pages\/Create\\n(create Page objects)\"]\n S5[\"5. Pages\/Convert\\n(Markdown -> HTML\\nfront matter)\"]\n S6[\"6. Taxonomies\/Create\\n(create taxonomies)\"]\n S7[\"7. Pages\/Generate\\n(generators)\"]\n S8[\"8. Menus\/Create\\n(create menus)\"]\n S9[\"9. StaticFiles\/Copy\\n(copy static files)\"]\n S10[\"10. Pages\/Render\\n(Twig rendering)\"]\n S11[\"11. Pages\/Save\\n(save pages)\"]\n S12[\"12. Assets\/Save\\n(save assets)\"]\n S13[\"13. Optimize\/*\\n(optimize HTML\/CSS\/JS\/Images)\"]\n\n S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10 --> S11 --> S12 --> S13\n end\n\n BUILDER --> PIPELINE\n\n %% Subsystems\n subgraph COLLECTIONS[\"Collections\"]\n PC[\"PagesCollection\\n(Page objects)\"]\n TC[\"TaxonomiesCollection\\n(vocabularies\/terms)\"]\n MC[\"MenusCollection\"]\n end\n\n subgraph GENERATORS[\"Generators (virtual pages)\"]\n GP[\"Pagination\"]\n GT[\"Taxonomy\"]\n GS[\"Section\"]\n GR[\"Redirect\"]\n GD[\"DefaultPages (home, 404)\"]\n end\n\n subgraph RENDERER[\"Twig rendering\"]\n TW[\"Twig engine\"]\n EXT[\"Extensions\\n(Core, Content, Collection)\"]\n PP[\"PostProcessors\\n(metadata, excerpts, links)\"]\n TH[\"Themes \/ Layouts\"]\n TW --> EXT\n TW --> PP\n TH --> TW\n end\n\n subgraph ASSETS[\"Assets\"]\n AL[\"Asset locator\"]\n AC[\"Compiler\\n(SCSS -> CSS)\"]\n AI[\"Image processor\\n(responsive, WebP, AVIF)\"]\n AO[\"Optimizer\\n(CSS\/JS minification)\"]\n end\n\n subgraph OUTPUT[\"Output (_site\/)\"]\n HTML[\".html pages\"]\n CSS2[\"CSS\/JS assets\"]\n IMG[\"images\"]\n SF[\"static files\"]\n end\n\n S4 --> PC\n S6 --> TC\n S8 --> MC\n S7 --> GENERATORS\n GENERATORS --> PC\n S10 --> RENDERER\n S12 --> ASSETS\n\n PC --> RENDERER\n TC --> RENDERER\n MC --> RENDERER\n\n RENDERER --> S11\n S11 --> HTML\n S12 --> CSS2\n S12 --> IMG\n S9 --> SF\n\n %% Inputs\n subgraph INPUT[\"Sources\"]\n MD[\"content\/\\n(Markdown + front matter)\"]\n DATA[\"data\/\\n(YAML)\"]\n STATIC[\"static\/\"]\n LAYOUTS[\"layouts\/\\n(Twig templates)\"]\n end\n\n MD --> S1\n DATA --> S2\n STATIC --> S3\n LAYOUTS --> TH\nKey Components Legend\n\n\n\nComponent\nRole\n\n\n\n\nBuilder\nCentral orchestrator that executes steps in sequence\n\n\nConfig\nMerges default + theme + project + CLI configuration\n\n\nSteps\nModular pipeline (13 steps), each with init() \/ canProcess() \/ process()\n\n\nCollections\nPages, Taxonomies, Menus: core data structures\n\n\nGenerators\nCreate virtual pages (pagination, tags, redirects, etc.)\n\n\nRenderer (Twig)\nApplies templates + extensions + post-processors\n\n\nAssets\nCompiles SCSS, optimizes images, fingerprints files\n\n\n", "content_html": "

Architecture

\n

Diagram

\n
graph TD\n    %% Entry\n    CLI[\"bin/cecil\\n(CLI entry point)\"]\n    APP[\"Application\\n(Symfony Console)\"]\n    CMD[\"Commands\\nbuild / serve / new:site\\nnew:page / clear / show:content\"]\n\n    CLI --> APP --> CMD\n\n    %% Orchestrator\n    BUILDER[\"Builder\\n(Orchestrator)\"]\n    CONFIG[\"Configuration\\n(config.yml + default.php\\n+ themes)\"]\n    CMD --> BUILDER\n    CONFIG --> BUILDER\n\n    %% Pipeline\n    subgraph PIPELINE[\"Build pipeline (steps)\"]\n        S1[\"1. Pages/Load\\n(Finder -> Markdown files)\"]\n        S2[\"2. Data/Load\\n(YAML files)\"]\n        S3[\"3. StaticFiles/Load\\n(load static files)\"]\n        S4[\"4. Pages/Create\\n(create Page objects)\"]\n        S5[\"5. Pages/Convert\\n(Markdown -> HTML\\nfront matter)\"]\n        S6[\"6. Taxonomies/Create\\n(create taxonomies)\"]\n        S7[\"7. Pages/Generate\\n(generators)\"]\n        S8[\"8. Menus/Create\\n(create menus)\"]\n        S9[\"9. StaticFiles/Copy\\n(copy static files)\"]\n        S10[\"10. Pages/Render\\n(Twig rendering)\"]\n        S11[\"11. Pages/Save\\n(save pages)\"]\n        S12[\"12. Assets/Save\\n(save assets)\"]\n        S13[\"13. Optimize/*\\n(optimize HTML/CSS/JS/Images)\"]\n\n        S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10 --> S11 --> S12 --> S13\n    end\n\n    BUILDER --> PIPELINE\n\n    %% Subsystems\n    subgraph COLLECTIONS[\"Collections\"]\n        PC[\"PagesCollection\\n(Page objects)\"]\n        TC[\"TaxonomiesCollection\\n(vocabularies/terms)\"]\n        MC[\"MenusCollection\"]\n    end\n\n    subgraph GENERATORS[\"Generators (virtual pages)\"]\n        GP[\"Pagination\"]\n        GT[\"Taxonomy\"]\n        GS[\"Section\"]\n        GR[\"Redirect\"]\n        GD[\"DefaultPages (home, 404)\"]\n    end\n\n    subgraph RENDERER[\"Twig rendering\"]\n        TW[\"Twig engine\"]\n        EXT[\"Extensions\\n(Core, Content, Collection)\"]\n        PP[\"PostProcessors\\n(metadata, excerpts, links)\"]\n        TH[\"Themes / Layouts\"]\n        TW --> EXT\n        TW --> PP\n        TH --> TW\n    end\n\n    subgraph ASSETS[\"Assets\"]\n        AL[\"Asset locator\"]\n        AC[\"Compiler\\n(SCSS -> CSS)\"]\n        AI[\"Image processor\\n(responsive, WebP, AVIF)\"]\n        AO[\"Optimizer\\n(CSS/JS minification)\"]\n    end\n\n    subgraph OUTPUT[\"Output (_site/)\"]\n        HTML[\".html pages\"]\n        CSS2[\"CSS/JS assets\"]\n        IMG[\"images\"]\n        SF[\"static files\"]\n    end\n\n    S4 --> PC\n    S6 --> TC\n    S8 --> MC\n    S7 --> GENERATORS\n    GENERATORS --> PC\n    S10 --> RENDERER\n    S12 --> ASSETS\n\n    PC --> RENDERER\n    TC --> RENDERER\n    MC --> RENDERER\n\n    RENDERER --> S11\n    S11 --> HTML\n    S12 --> CSS2\n    S12 --> IMG\n    S9 --> SF\n\n    %% Inputs\n    subgraph INPUT[\"Sources\"]\n        MD[\"content/\\n(Markdown + front matter)\"]\n        DATA[\"data/\\n(YAML)\"]\n        STATIC[\"static/\"]\n        LAYOUTS[\"layouts/\\n(Twig templates)\"]\n    end\n\n    MD --> S1\n    DATA --> S2\n    STATIC --> S3\n    LAYOUTS --> TH
\n

Key Components Legend

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ComponentRole
BuilderCentral orchestrator that executes steps in sequence
ConfigMerges default + theme + project + CLI configuration
StepsModular pipeline (13 steps), each with init() / canProcess() / process()
CollectionsPages, Taxonomies, Menus: core data structures
GeneratorsCreate virtual pages (pagination, tags, redirects, etc.)
Renderer (Twig)Applies templates + extensions + post-processors
AssetsCompiles SCSS, optimizes images, fingerprints files
", "language": "en" }, { "id": "https://cecil.app/documentation/developers/library/", "url": "https://cecil.app/documentation/developers/library/", "title": "Library", "summary": "Use Cecil as a PHP library: install it with Composer, then build and diagnose programmatically.", "date_published": "2023-12-13T00:00:00+00:00", "date_modified": "2026-10-03T00:00:00+00:00","content_text": "Library\nCecil provides a simple PHP API to build your website.\nYou can read the API documentation for more details.\nInstallation\ncomposer require cecil\/cecil\nlibvips support\nTo process images with libvips (optional), install the libvips driver in your project:\ncomposer require intervention\/image-driver-vips\nThis driver requires libvips installed on your system and the PHP FFI extension enabled.\nWithout it, Cecil uses Imagick or GD instead.\nUsage\nBuild\nBuild a new website with a custom configuration:\nrequire_once 'vendor\/autoload.php';\n\nuse Cecil\\Builder;\n\n$config = [\n 'title' => \"My website\",\n 'baseurl' => 'https:\/\/domain.tld\/',\n];\n\nBuilder::create($config)->build();\n\nexec('php -S localhost:8000 -t _site'); \/\/ preview locally\nThe main parameter of the create method should be a PHP array or a Cecil\\Config instance.\nDiagnostic\nYou can also run doctor checks through dedicated domain services, without using CLI commands.\n<?php\n\nrequire_once 'vendor\/autoload.php';\n\nuse Cecil\\Builder;\nuse Cecil\\Doctor\\SeoDoctor;\nuse Cecil\\Doctor\\SiteDoctor;\n\n$builder = Builder::create(require 'config.php')\n ->setSourceDir(__DIR__)\n ->setDestinationDir(__DIR__);\n\n$siteDoctor = new SiteDoctor();\n$diagnosis = $siteDoctor->diagnose($builder, __DIR__, ['cecil.yml']);\n\n$seoDoctor = new SeoDoctor();\n$seoAudit = $seoDoctor->audit($builder, [\n 'page' => '',\n 'include_virtual' => false,\n]);\n\nvar_dump($diagnosis['errors'], $seoAudit['summary']);", "content_html": "

Library

\n

Cecil provides a simple PHP API to build your website.

\n

You can read the API documentation for more details.

\n

Installation

\n
composer require cecil/cecil
\n

libvips support

\n

To process images with libvips (optional), install the libvips driver in your project:

\n
composer require intervention/image-driver-vips
\n\n

Usage

\n

Build

\n

Build a new website with a custom configuration:

\n
require_once 'vendor/autoload.php';\n\nuse Cecil\\Builder;\n\n$config = [\n    'title'   => \"My website\",\n    'baseurl' => 'https://domain.tld/',\n];\n\nBuilder::create($config)->build();\n\nexec('php -S localhost:8000 -t _site'); // preview locally
\n\n

Diagnostic

\n

You can also run doctor checks through dedicated domain services, without using CLI commands.

\n
<?php\n\nrequire_once 'vendor/autoload.php';\n\nuse Cecil\\Builder;\nuse Cecil\\Doctor\\SeoDoctor;\nuse Cecil\\Doctor\\SiteDoctor;\n\n$builder = Builder::create(require 'config.php')\n    ->setSourceDir(__DIR__)\n    ->setDestinationDir(__DIR__);\n\n$siteDoctor = new SiteDoctor();\n$diagnosis = $siteDoctor->diagnose($builder, __DIR__, ['cecil.yml']);\n\n$seoDoctor = new SeoDoctor();\n$seoAudit = $seoDoctor->audit($builder, [\n    'page' => '',\n    'include_virtual' => false,\n]);\n\nvar_dump($diagnosis['errors'], $seoAudit['summary']);
", "language": "en" }, { "id": "https://cecil.app/documentation/developers/extend/", "url": "https://cecil.app/documentation/developers/extend/", "title": "Extend", "summary": "Create custom pages generators, add Twig extensions and post-process output files.", "date_published": "2023-04-17T00:00:00+00:00", "date_modified": "2026-10-02T00:00:00+00:00","content_text": "Extend\nBecause Cecil is powered by PHP it's easy to extend its capabilities.\nPages Generator\nA generator helps you create pages without Markdown files (for example, with data from an API or a database) or alter existing pages.\nJust create a new PHP class in the Cecil\\Generator namespace and add the class name to the pages.generators list.\nExample:\n\/extensions\/Cecil\/Generator\/DummyPage.php\n<?php\nnamespace Cecil\\Generator;\n\nuse Cecil\\Collection\\Page\\Page;\nuse Cecil\\Collection\\Page\\Type;\n\nclass DummyPage extends AbstractGenerator implements GeneratorInterface\n{\n public function generate(): void\n {\n \/\/ create a new page $page, then add it to the site collection\n $page = (new Page('my-page'))\n ->setType(Type::PAGE->value)\n ->setPath('mypage')\n ->setBodyHtml('<p>My page body<\/p>')\n ->setVariable('language', 'en')\n ->setVariable('title', 'My page')\n ->setVariable('date', now())\n ->setVariable('menu', ['main' => ['weight' => 99]]);\n $this->generatedPages->add($page);\n }\n}\n\/extensions\/Cecil\/Generator\/Database.php\n<?php\nnamespace Cecil\\Generator;\n\nuse Cecil\\Collection\\Page\\Page;\nuse Cecil\\Collection\\Page\\Type;\n\nclass Database extends AbstractGenerator implements GeneratorInterface\n{\n public function generate(): void\n {\n \/\/ create pages from a SQLite database\n $db = new SQLite3('database.sqlite');\n $statement = $db->prepare('SELECT * FROM blog');\n $result = $statement->execute();\n while ($row = $result->fetchArray(SQLITE3_ASSOC)) {\n $page = (new Page($row['page-id']))\n ->setType(Type::PAGE->value)\n ->setPath($row['path'])\n ->setBodyHtml($row['html'])\n ->setVariable('title', $row['title'])\n ->setVariable('date', $row['date']);\n $this->generatedPages->add($page);\n }\n $result->finalize();\n $db->close();\n }\n}\nconfiguration\npages:\n generators:\n # priority: class name\n 99: Cecil\\Generator\\DummyPage\n 35: Cecil\\Generator\\Database\nTwig extension\nYou can add custom functions and filters:\n\ncreate a Twig extension in the Cecil\\Renderer\\Extension namespace\nadd the PHP file in the extensions directory\nadd the class name to the configuration\n\nExample:\n\/extensions\/Cecil\/Renderer\/Extension\/MyTwigExtension.php\n<?php\nnamespace Cecil\\Renderer\\Extension;\n\nclass MyTwigExtension extends \\Twig\\Extension\\AbstractExtension\n{\n public function getFilters()\n {\n \/\/ add a new filter named 'md5'\n return [\n new \\Twig\\TwigFilter('md5', 'md5'),\n ];\n }\n}\nconfiguration\nlayouts:\n extensions:\n MyExtension: Cecil\\Renderer\\Extension\\MyTwigExtension\nOutput Post Processor\nYou can post process page output.\nJust create a new PHP class in the Cecil\\Renderer\\PostProcessor namespace and add the class name to the `output.postprocessors list.\nExample:\n\/extensions\/Cecil\/Renderer\/PostProcessor\/MyProcessor.php\n<?php\nnamespace Cecil\\Renderer\\PostProcessor;\n\nuse Cecil\\Collection\\Page\\Page;\n\nclass MyProcessor extends AbstractPostProcessor\n{\n public function process(Page $page, string $output, string $format): string\n {\n \/\/ add a meta tag to the head of the HTML output\n if ($format == 'html') {\n if (!preg_match('\/<meta name=\"test\".*\/i', $output)) {\n $meta = \\sprintf('<meta name=\"test\" content=\"Test\">');\n $output = preg_replace_callback('\/([[:blank:]]*)(<\\\/head>)\/i', function ($matches) use ($meta) {\n return str_repeat($matches[1] ?: ' ', 2) . $meta . \"\\n\" . $matches[1] . $matches[2];\n }, $output);\n }\n }\n\n return $output;\n }\n}\nconfiguration\noutput:\n postprocessors:\n MyProcessor: Cecil\\Renderer\\PostProcessor\\MyProcessor", "content_html": "

Extend

\n

Because Cecil is powered by PHP it's easy to extend its capabilities.

\n

Pages Generator

\n

A generator helps you create pages without Markdown files (for example, with data from an API or a database) or alter existing pages.

\n

Just create a new PHP class in the Cecil\\Generator namespace and add the class name to the pages.generators list.

\n

Example:

\n

/extensions/Cecil/Generator/DummyPage.php

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

/extensions/Cecil/Generator/Database.php

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

configuration

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

Twig extension

\n

You can add custom functions and filters:

\n
    \n
  1. create a Twig extension in the Cecil\\Renderer\\Extension namespace
    2. \n
  2. add the PHP file in the extensions directory
    3. \n
  3. add the class name to the configuration
    4. \n
\n

Example:

\n

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

\n
<?php\nnamespace Cecil\\Renderer\\Extension;\n\nclass MyTwigExtension extends \\Twig\\Extension\\AbstractExtension\n{\n    public function getFilters()\n    {\n        // add a new filter named 'md5'\n        return [\n            new \\Twig\\TwigFilter('md5', 'md5'),\n        ];\n    }\n}
\n

configuration

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

Output Post Processor

\n

You can post process page output.

\n

Just create a new PHP class in the Cecil\\Renderer\\PostProcessor namespace and add the class name to the `output.postprocessors list.

\n

Example:

\n

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

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

configuration

\n
output:\n  postprocessors:\n    MyProcessor: Cecil\\Renderer\\PostProcessor\\MyProcessor
", "language": "en" } ] }