What's on this page
Architecture
This page gives an overview of Cecil’s build pipeline, its technical architecture and its key components.
Build pipeline
Pipeline overview
graph LR
SRC["Sources\n(pages, data, assets,\nstatic, layouts, themes)"]
CFG["Configuration"]
EXTS["Extensions\n(plugins, events)"]
BUILDER["Builder"]
LOAD["Load\n(pages, data,\nstatic files)"]
CONVERT["Create & convert\n(pages, taxonomies)"]
GENERATE["Generate\n(generators, menus)"]
RENDER["Render\n(Twig)"]
SAVE["Save & optimize\n(pages, assets,\nstatic files)"]
OUT["_site/"]
CFG --> BUILDER
EXTS --> BUILDER
SRC --> LOAD
BUILDER --> LOAD --> CONVERT --> GENERATE --> RENDER --> SAVE --> OUT
Detailed pipeline
graph TD
%% Entry
CLI["bin/cecil\n(CLI entry point)"]
APP["Application\n(Symfony Console)"]
CMD["Commands\nbuild / serve / doctor\nnew:* / clear / cache:clear\nshow:* / util:* / ..."]
CLI --> APP --> CMD
%% Orchestrator
BUILDER["Builder\n(Orchestrator)"]
CONFIG["Configuration\n(plugins < default.php\n< themes < cecil.yml\n< env vars + CLI options)"]
CMD --> BUILDER
CONFIG --> BUILDER
%% Extensions
EXTN["Extensions\n(Autoloader + Loader:\nplugins, event subscribers,\ngenerators, Twig extensions,\npost-processors)"]
EVENTS["Build events\n(build.*, step.*, page.*)"]
BUILDER --> EXTN
EXTN -- "plugins config" --> CONFIG
BUILDER -. "dispatch" .-> EVENTS
EVENTS -. "notify subscribers" .-> EXTN
%% Pipeline
subgraph PIPELINE["Build pipeline (steps)"]
S1["1. Pages/Load\n(Finder → Markdown files)"]
S2["2. Data/Load\n(data files)"]
S3["3. StaticFiles/Load\n(if static.load is enabled)"]
S4["4. Pages/Create\n(create Page objects)"]
S5["5. Pages/Convert\n(front matter +\nMarkdown → HTML)"]
S6["6. Taxonomies/Create\n(create taxonomies)"]
S7["7. Pages/Generate\n(generators)"]
S8["8. Menus/Create\n(create menus)"]
S9["9. StaticFiles/Copy\n(copy static files)"]
S10["10. Pages/Render\n(Twig rendering)"]
S11["11. Pages/Save\n(save pages)"]
S12["12. Assets/Save\n(save assets)"]
S13["13-16. Optimize/Html, Css, Js, Images\n(if optimization is enabled)"]
S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10 --> S11 --> S12 --> S13
end
BUILDER --> PIPELINE
%% Subsystems
CONV["Converter\n(pages.converter, pages.body.parser:\nParsedown + highlighter)"]
subgraph COLLECTIONS["Collections"]
PC["PagesCollection\n(Page objects)"]
TC["TaxonomiesCollection\n(vocabularies/terms)"]
MC["MenusCollection"]
end
subgraph GENERATORS["Generators (by priority)"]
G1["DefaultPages\n(index, 404, robots, sitemap, xsl)"]
G3["ExternalBody"]
G4["Section"]
G5["Taxonomy"]
G6["Homepage"]
G7["Pagination"]
G8["Alias"]
G9["Redirect"]
G10["Custom generators\n(priority 100 by default)"]
G1 --> G3 --> G4 --> G5 --> G6 --> G7 --> G8 --> G9 --> G10
end
subgraph RENDERER["Twig rendering"]
TW["Twig engine"]
EXT["Twig extensions\n(Core, Content, Collection,\nTranslation, Intl, Components\n+ custom)"]
PP["PostProcessors\n(generator meta tag, excerpts, links\n+ custom)"]
TH["Themes / Layouts"]
TW --> EXT
TW --> PP
TH --> TW
end
subgraph ASSETS["Assets"]
AL["Asset locator"]
AC["Compiler\n(SCSS → CSS)"]
AI["Image processor\n(resize, responsive, WebP, AVIF)"]
AO["Optimizer\n(CSS/JS minification,\nimage optimization)"]
end
CACHE[".cache/\n(assets, templates, translations)"]
subgraph OUTPUT["Output (_site/)"]
HTML["pages (HTML, XML, JSON, etc.)"]
CSS2["CSS/JS assets"]
IMG["images"]
SF["static files"]
end
S5 --> CONV
S4 --> PC
S6 --> TC
S8 --> MC
S7 --> GENERATORS
GENERATORS --> PC
S10 --> RENDERER
EXTN --> GENERATORS
EXTN --> EXT
EXTN --> PP
PIPELINE -. "step.*, page.*" .-> EVENTS
PC --> RENDERER
TC --> RENDERER
MC --> RENDERER
S2 -- "site.data" --> RENDERER
S3 -- "site.static" --> RENDERER
%% assets are created by the converter (Markdown images, links) and by templates (asset() function),
%% processed and stored in cache, then copied to the output
CONV --> ASSETS
EXT --> ASSETS
ASSETS --> CACHE
CACHE --> S12
RENDERER --> S11
S11 --> HTML
S12 --> CSS2
S12 --> IMG
S9 --> SF
S13 -. "optimize files in place" .-> OUTPUT
%% Inputs
subgraph INPUT["Sources"]
MD["pages/\n(Markdown + front matter)"]
DATA["data/\n(YAML, JSON, XML, CSV)"]
STATIC["static/"]
ASSETSDIR["assets/"]
LAYOUTS["layouts/\n(Twig templates)"]
TRANS["translations/"]
THEMES["themes/\n(config, layouts, assets,\nstatic, data, translations,\nextensions)"]
EXTDIR["extensions/\n(PHP classes)"]
end
MD --> S1
DATA --> S2
STATIC --> S3
STATIC --> S9
ASSETSDIR --> AL
LAYOUTS --> TH
TRANS --> EXT
THEMES --> CONFIG
THEMES --> TH
THEMES --> EXTN
EXTDIR --> EXTN
Technical architecture
The diagrams below show how the code is organized in layers, from the command line to the file system, and which libraries each component relies on.
Architecture overview
graph TB
ENTRY["Entry points\n(bin/cecil, cecil.phar)"]
CONSOLE["Console\n(commands)"]
DEV["Local server\n(serve, live reload)"]
CORE["Core\n(Builder, Config, Steps,\nCollections, Generators)"]
EXTS["Extensions\n(plugins, events)"]
SERVICES["Services\n(Converter, Renderer,\nAssets, Cache, Doctor)"]
LIBS["Libraries\n(Symfony, Twig, Parsedown,\nscssphp, Intervention Image, ...)"]
FS["File system\n(sources, .cache/, _site/)"]
ENTRY --> CONSOLE --> CORE
CONSOLE --> DEV --> CORE
CORE <--> EXTS
CORE --> SERVICES
CORE --> FS
SERVICES --> FS
SERVICES --> LIBS
Detailed architecture
graph TB
%% Distribution and entry points
subgraph ENTRY["Entry points"]
BIN["bin/cecil\n(Composer)"]
PHAR["cecil.phar\n(Box, self-update)"]
end
subgraph CONSOLE["Console layer (Symfony Console)"]
APP["Application"]
ENV[".env\n(phpdotenv)"]
BUILD["build"]
SERVE["serve"]
DOCTOR["doctor:*"]
OTHERS["new:* / show:* / clear / cache:clear / util:*"]
APP --> BUILD
APP --> SERVE
APP --> DOCTOR
APP --> OTHERS
ENV --> APP
end
BIN --> APP
PHAR --> APP
subgraph DEV["Local server (serve)"]
PHPS["PHP built-in server\n(.cecil/router.php)"]
WATCH["FileWatcher\n(changes.flag)"]
PROC["Build sub-process\n(Symfony Process)"]
LR["livereload.js\n(Server-Sent Events)"]
WATCH -- "rebuild" --> PROC
WATCH -- "notify" --> PHPS
PHPS --> LR
end
SERVE --> DEV
subgraph CORE["Core"]
BUILDER["Builder\n(steps orchestration, metrics)"]
CFG["Config\n(Merger, Deprecations,\nnette/schema)"]
LOG["Logger\n(PSR-3: Console, Progress, Print)"]
STEPS["Steps\n(StepInterface)"]
COLL["Collections\n(Page, Taxonomy, Menu)"]
GEN["Generators\n(GeneratorManager)"]
BUILDER --> CFG
BUILDER --> LOG
BUILDER --> STEPS
STEPS --> COLL
STEPS --> GEN
end
BUILD --> BUILDER
PROC --> BUILDER
OTHERS --> BUILDER
subgraph EXTS["Extensions"]
AUTO["Autoloader\n(extensions/, PSR-4,\nextensions/vendor/)"]
LOADER["Loader\n(by name and priority,\nextensions.strict)"]
PLUG["Plugins\n(Registry)"]
EVT["Event dispatcher\n(BuildEvents, subscribers)"]
PLUG --> LOADER
end
BUILDER --> AUTO
BUILDER --> PLUG
PLUG -- "default config" --> CFG
BUILDER -- "dispatch" --> EVT
STEPS -- "dispatch" --> EVT
LOADER --> GEN
subgraph SERVICES["Services"]
CONV["Converter\n(ConverterInterface, Parsedown Extra + TOC,\nhighlight.php / Tempest)"]
REND["Renderer\n(Twig, Symfony Translation,\nTwig Components)"]
ASSET["Asset\n(Locator, Compiler, Image, Optimizer)"]
CACHE["Cache\n(PSR-16, files)"]
DOC["Doctor\n(Site, Frontmatter, Links, SEO)"]
end
STEPS --> CONV
STEPS --> REND
STEPS --> ASSET
REND --> ASSET
CONV --> ASSET
ASSET --> CACHE
REND --> CACHE
DOCTOR --> DOC
DOC --> BUILDER
LOADER --> REND
subgraph LIBS["Main libraries"]
L1["Symfony\n(Finder, Filesystem, Yaml, Serializer,\nValidator, DomCrawler, EventDispatcher)"]
L2["scssphp"]
L3["Intervention Image\n(GD, Imagick, libvips)"]
L4["matthiasmullie/minify\nvoku/html-min"]
L5["spatie/image-optimizer\n(external binaries)"]
L6["yosymfony/toml"]
L7["getID3, mp3info\n(audio/video metadata)"]
end
CORE --> L1
ASSET --> L2
ASSET --> L3
ASSET --> L4
STEPS --> L4
ASSET --> L5
CONV --> L6
ASSET --> L7
subgraph FS["File system"]
SRC["Sources\n(pages/, data/, assets/, static/,\nlayouts/, translations/, themes/,\nextensions/)"]
CACHEDIR[".cache/"]
TMP[".cecil/\n(router, live reload, metrics, logs)"]
OUT["_site/"]
end
STEPS -- "read" --> SRC
AUTO -- "read" --> SRC
CACHE --> CACHEDIR
STEPS -- "write" --> OUT
PHPS -- "serve" --> OUT
DEV --> TMP
Key components
| Component | Role |
|---|---|
| Builder | Central orchestrator that executes steps in sequence |
| Config | Merges plugins, default, themes and project configuration (Config\Merger), environment variables (CECIL_*) and CLI options, and reports deprecated options (Config\Deprecations) |
| Steps | Modular pipeline (16 steps), each with init() / canProcess() / process() |
| Collections | Pages, Taxonomies, Menus: core data structures |
| Converter | Parses the front matter (YAML, INI, TOML or JSON) and converts Markdown to HTML (Parsedown, code highlighting); replaceable with pages.converter and pages.body.parser |
| Generators | Create or update pages (default pages, sections, taxonomies, pagination, aliases, redirects, etc.) |
| Extensions | Generators, Twig extensions, post-processors, event subscribers and plugins declared by name, loaded and validated by Extension\Loader, autoloaded by Extension\Autoloader |
| Events | Build events (Event\BuildEvents) dispatched around the build, each step and each page lifecycle, to extend Cecil |
| Renderer (Twig) | Applies templates + extensions + post-processors |
| Assets | Created from Markdown content and templates: compiles SCSS, minifies, resizes and converts images, fingerprints files |
| Cache | Stores processed assets, compiled templates and translations in .cache/ to speed up subsequent builds |
| Doctor | Diagnoses the project: front matter, links, SEO, cache (doctor commands) |