![\"New](\"/docs/cecil-newsite.94982e8ace758b40e6ff753807bdb42b.png\")
\nCecil is distributed as a single executable file, cecil.phar, which runs anywhere PHP is installed, and as standalone binaries that don't require PHP.
fileinfo, gd and mbstringCheck your PHP version and loaded extensions:
\nphp -v\nphp -m| Extension | \nUsage | \n
|---|---|
intl | \nDates localization with other locales than en (improves performance otherwise). | \n
imagick | \nImage processing, preferred over GD when available. | \n
ffi | \nImage processing with libvips (requires Composer installation). | \n
Download cecil.phar from your terminal:
curl -LO https://cecil.app/cecil.pharThen run it with PHP:
\nphp cecil.phar --versionIf PHP is not installed, download the standalone binary for your platform from the latest GitHub release. It embeds PHP and the required extensions.
\n| Platform | \nFile | \n
|---|---|
| Linux x64 | \ncecil-linux-x64 | \n
| Linux ARM64 | \ncecil-linux-arm64 | \n
| macOS Intel | \ncecil-macos-x64 | \n
| macOS Apple Silicon | \ncecil-macos-arm64 | \n
| Windows x64 | \ncecil-windows-x64.exe | \n
For example, on Linux x64:
\ncurl -Lo cecil https://github.com/Cecilapp/Cecil/releases/latest/download/cecil-linux-x64\nchmod +x cecil\n./cecil --versionOn macOS, binaries are not signed: remove the quarantine attribute before the first run with xattr -d com.apple.quarantine cecil.
Installing Cecil globally allows you to run the cecil command from any directory, instead of php cecil.phar.
With Homebrew:
\nbrew install cecilapp/tap/cecilOr manually, by moving the PHAR in a directory of your PATH:
mv cecil.phar /usr/local/bin/cecil\nchmod +x /usr/local/bin/cecilWith Scoop:
\nscoop install https://cecil.app/scoop/cecil.jsonOr manually:
\ncecil.phar in a dedicated directory, like C:\\bincecil.phar to cecil;C:\\bin to your PATH environment variableWith PHIVE (The PHAR Installation and Verification Environment):
\nphive install cecilWith Composer:
\ncomposer global require cecil/cecilcecil --versionUpdate Cecil to the latest version according to your installation method:
\n# PHAR\nphp cecil.phar self-update\n# Homebrew\nbrew upgrade cecilapp/tap/cecil\n# Scoop\nscoop update cecil\n# PHIVE\nphive update cecil\n# Composer\ncomposer global update cecil/cecilThe standalone binary is updated by downloading it again.
\nThe self-update command (PHAR only) also accepts the following options:
--rollback: reverts to the previous installed version--stable: forces an update to the last stable version--preview: forces an update to the last unstable versioncommand not found: cecilThe installation directory is not in your PATH: add it, or run Cecil with php cecil.phar from the directory containing the PHAR.
Your PHP CLI may differ from the one you expect (several versions installed): check it with php -v and php --ini, then enable missing extensions in the loaded php.ini file.
Once a website is created, run the doctor command to diagnose its configuration.
This page gives an overview of Cecil’s build pipeline and its key components.
\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| Component | \nRole | \n
|---|---|
| Builder | \nCentral orchestrator that executes steps in sequence | \n
| Config | \nMerges default + theme + project + CLI configuration | \n
| Steps | \nModular pipeline (13 steps), each with init() / canProcess() / process() | \n
| Collections | \nPages, Taxonomies, Menus: core data structures | \n
| Generators | \nCreate virtual pages (pagination, tags, redirects, etc.) | \n
| Renderer (Twig) | \nApplies templates + extensions + post-processors | \n
| Assets | \nCompiles SCSS, optimizes images, fingerprints files | \n
Cecil provides a simple PHP API to build your website.
\nYou can read the API documentation for more details.
\ncomposer require cecil/cecilTo process images with libvips (optional), install the libvips driver in your project:
\ncomposer require intervention/image-driver-vipsBuild 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 locallyYou can also run doctor checks through dedicated domain services, without using CLI commands.
\n\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']);Examples of CDN providers configuration.
assets:\n images:\n cdn:\n enabled: true\n account: 'xxxx'\n url: 'https://res.cloudinary.com/%account%/image/fetch/c_limit,w_%width%,q_%quality%,f_%format%,d_default/%image_url%'assets:\n images:\n cdn:\n enabled: true\n account: 'xxxx'\n url: 'https://%account%.cloudimg.io/%image_url%?w=%width%&q=%quality%&force_format=%format%'assets:\n images:\n cdn:\n enabled: true\n account: 'xxxx'\n canonical: false\n remote: false\n url: 'https://%account%.twic.pics/%image_url%?twic=v1/resize=%width%/quality=%quality%/output=%format%'Source URL: Your website baseurl.
assets:\n images:\n cdn:\n enabled: true\n account: 'xxxx'\n canonical: false\n remote: false\n url: 'https://%account%.imgix.net/%image_url%?w=%width%&q=%quality%&fm=%format%'Base URL: Your website baseurl.
https://docs.netlify.com/image-cdn/overview/
\nassets:\n images:\n cdn:\n enabled: true\n canonical: false\n url: '/.netlify/images?url=%image_url%&w=%width%&fm=%format%'npm install netlify-cli -g\nnetlify linknetlify.toml:
[dev]\n targetPort = 8000php cecil.phar serve & netlify devBecause Cecil is powered by PHP it's easy to extend its capabilities.
\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.
Example:
\n/extensions/Cecil/Generator/DummyPage.php
\n\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}/extensions/Cecil/Generator/Database.php
\n\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}configuration
\npages:\n generators:\n # priority: class name\n 99: Cecil\\Generator\\DummyPage\n 35: Cecil\\Generator\\DatabaseYou can add custom functions and filters:
\nCecil\\Renderer\\Extension namespaceextensions directoryExample:
\n/extensions/Cecil/Renderer/Extension/MyTwigExtension.php
\n\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}configuration
\nlayouts:\n extensions:\n MyExtension: Cecil\\Renderer\\Extension\\MyTwigExtensionYou 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.
Example:
\n/extensions/Cecil/Renderer/PostProcessor/MyProcessor.php
\n\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}configuration
\noutput:\n postprocessors:\n MyProcessor: Cecil\\Renderer\\PostProcessor\\MyProcessorCecil provides Twig functions and filters to resize, crop and convert images, and to generate responsive images and placeholders.
\nBuilds the HTML img srcset (responsive) attribute of an image Asset.
{{ image_srcset(asset) }}Examples:
\n{% set asset = asset(image_path) %}\n<img src=\"{{ url(asset) }}\" width=\"{{ asset.width }}\" height=\"{{ asset.height }}\" alt=\"\" class=\"asset\" srcset=\"{{ image_srcset(asset) }}\" sizes=\"{{ image_sizes('asset') }}\">Returns the HTML img sizes attribute based on a CSS class name.
\nIt should be use in conjunction with the image_srcset function.
{{ image_sizes('class') }}Examples:
\n{% set asset = asset(image_path) %}\n<img src=\"{{ url(asset) }}\" width=\"{{ asset.width }}\" height=\"{{ asset.height }}\" alt=\"\" class=\"asset\" srcset=\"{{ image_srcset(asset) }}\" sizes=\"{{ image_sizes('asset') }}\">Builds the HTML img element from a website URL by extracting its illustration image.\nReturns null if no image is found.
{{ image_from_website('url', {attributes}, {options}) }}The image is searched in the page HTML with the following fallbacks, the first candidate that can be downloaded as an image is used:
\nog:image:secure_url, og:image, og:image:urltwitter:image, twitter:image:src<link rel=\"image_src\">itemprop=\"image\"image property<img> of <article>, <main> or <body><link rel=\"apple-touch-icon\"><link rel=\"icon\">Relative URLs are resolved against <base href> or the page URL.
The resolved image URL and the downloaded image are cached (see cache.assets.remote.ttl).
Options:
\nfallback: image path (or URL) used if no image is foundimage options (e.g.: responsive, formats)Examples:
\n{{ image_from_website('https://example.com/page-with-image.html') }}\n\n{# with a fallback image #}\n{{ image_from_website('https://example.com/', {alt: 'Illustration'}, {fallback: 'images/default.png'}) }}Resizes an image to a specified width (in pixels) or/and height (in pixels).
\n{{ asset(image_path)|resize(width: width, height: height, remove_animation: bool) }}Examples:
\n{{ asset(page.image)|resize(300) }}\n{# equivalent to: #}\n{{ asset(page.image)|resize(width: 300) }}\n{# resizes to 300px width, height auto-calculated to preserve aspect ratio #}\n{{ asset(page.image)|resize(height: 200) }}\n{# resizes to 300px width and 200px height, and crops if necessary #}\n{{ asset(page.image)|resize(300, 200) }}\n{# removes any animation from the image #}\n{{ asset(page.image)|resize(width: 1200, height: 630, remove_animation: true) }}Resizes an image to a specified width and height, cropping it if necessary.
\n\n{{ asset(image_path)|cover(width, height) }}Example:
\n{{ asset(page.image)|cover(1200, 630) }}Adds padding, in pourcentages, to an image to make it maskable.
\n{{ asset(image_path)|maskable(padding) }}Example:
\n{{ asset('icon.png')|maskable }}Converts an image to WebP format.
\nExample:
\n<picture>\n <source type=\"image/webp\" srcset=\"{{ asset(image_path)|webp }}\">\n <img src=\"{{ url(asset(image_path)) }}\" width=\"{{ asset(image_path).width }}\" height=\"{{ asset(image_path).height }}\" alt=\"\">\n</picture>Converts an image to AVIF format.
\nExample:
\n<picture>\n <source type=\"image/avif\" srcset=\"{{ asset(image_path)|avif }}\">\n <img src=\"{{ url(asset(image_path)) }}\" width=\"{{ asset(image_path).width }}\" height=\"{{ asset(image_path).height }}\" alt=\"\">\n</picture>Returns a Low Quality Image Placeholder (100x100 px, 50% blurred) as data URL.
\n{{ asset(image_path)|lqip }}Returns the dominant hexadecimal color of an image.
\n{{ asset(image_path)|dominant_color }}These options define the main settings of the site: title, URL, description, menus, taxonomies, theme, metatags, etc.
\nMain title of the site.
\ntitle: \"<site title>\"Short description (~ 20 characters).
\nbaseline: \"<baseline>\"The base URL.
\nbaseurl: <url>Example:
\nbaseurl: http://localhost:8000/If set to true the url() function will return the absolute URL (false by default).
canonicalurl: <true|false> # false by defaultSite description (~ 250 characters).
\ndescription: \"<description>\"Menus are used to create navigation links in templates.
\nA menu is made up of a unique ID and entry properties (name, URL, weight).
\nmenus:\n <name>:\n - id: <unique-id> # unique identifier (required)\n name: \"<name>\" # name displayed in templates\n url: <url> # relative or absolute URL\n weight: <integer> # integer value used to sort entries (lighter first)Example:
\nmenus:\n main:\n - id: about\n name: \"About\"\n url: /about/\n weight: 1\n footer:\n - id: author\n name: The author\n url: https://arnaudligny.fr\n weight: 99A page menu entry can be overridden: use the page ID as id.
Example:
\nmenus:\n main:\n - id: index\n name: \"My amazing homepage!\"\n weight: 1A menu entry can be disabled with enabled: false.
Example:
\nmenus:\n main:\n - id: about\n enabled: falseList of vocabularies, paired by plural and singular value.
\ntaxonomies:\n <plural>: <singular>Example:
\ntaxonomies:\n categories: category\n tags: tagThen you can use those vocabularies in your content’s front matter.
\n\n\nThe theme to use, or a list of themes.
\ntheme: <theme> # theme name\n# or\ntheme:\n - <theme1> # theme name\n - <theme2>Examples:
\ntheme: hydetheme:\n - serviceworker\n - hydeDate format and timezone.
\ndate:\n format: <format> # date format (optional, `F j, Y` by default)\n timezone: <timezone> # date timezone (optional, local time zone by default)Example:
\ndate:\n format: 'j F, Y'\n timezone: 'Europe/Paris'metatags are SEO and social helpers that can be automatically injected in the <head>, with the template partials/metatags.html.twig.
This template adds the following meta tags:
\nrel=me linksCecil uses page front matter to feed meta tags, and falls back to site options when needed.
\ntitle: \"Page/Site title\" # used by title meta\ndescription: \"Page/Site description\" # used by description meta\ntags: [tag1, tag2] # used by keywords meta\nkeywords: [keyword1, keyword2] # obsolete\nauthor: # used by author meta\n name: <name> # author name\n url: <url> # author URL\n email: <email> # author email\nimage: image.jpg # used by Open Graph and social networks cards\ncanonical: # used to override the generated canonical URL\n url: <URL> # absolute URL\n title: \"<URL title>\" # optional canonical title\nsocial: # used by social networks meta\n twitter: # used by Twitter/X Card\n url: <URL> # used for `rel=me` link\n site: username # site username\n creator: username # page author username\n mastodon: # used by Mastodon meta\n url: <URL> # used for `rel=me` link\n creator: handle # page author account\n facebook: # used by Facebook meta\n url: <URL> # used for `rel=me` link\n id: 123456789 # Facebook profile ID\n username: username # page author usernamemetatags:\n title: # title options\n divider: \" · \" # string between page title and site title\n only: false # displays page title only (`false` by default)\n pagination: # pagination options\n shownumber: true # displays page number in title (`true` by default)\n label: \"Page %s\" # how to display page number (`Page %s` by default)\n robots: \"index,follow\" # web crawlers directives (`index,follow` by default)\n favicon: # favicon options\n enabled: true # includes favicon (`true` by default)\n image: favicon.png # path to favicon image\n sizes: # sizes by device\n - \"icon\": [32, 57, 76, 96, 128, 192, 228] # web browsers\n - \"shortcut icon\": [196] # Android\n - \"apple-touch-icon\": [120, 152, 180] # iOS\n navigation: true # includes previous and next links (`true` by default)\n image: true # includes image (`true` by default)\n og: true # includes Open Graph meta tags (`true` by default)\n articles: \"blog\" # articles' section (`blog` by default)\n twitter: true # includes Twitter/X Card meta tags (`true` by default)\n mastodon: true # includes Mastodon meta tags (`true` by default)\n dc: false # includes Dublin Core meta tags (`false` by default)\n data: false # includes JSON-LD structured data (`false` by default)Enables the debug mode, used to display debug information like very verbose logs, Twig dump, Twig profiler, SCSS sourcemap, etc.
\ndebug: trueThere are two other ways to enable debug mode:
\n-vvv optionCECIL_DEBUG environment variable to trueA page is a file made up of a front matter and a body.
\nThe front matter is a collection of variables (in key/value format) surrounded by ---.
Example:
\n\ntitle: \"The title\"\ndate: 2019-02-21\ntags: [tag 1, tag 2]\ncustomvar: \"Value of customvar\"\nBody is the main content of a page, it could be written in Markdown or in plain text.
\nExample:
\n# Header\n\n[toc]\n\n## Sub-Header 1\n\nLorem ipsum dolor [sit amet](https://example.com), consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n<!-- excerpt -->\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n\n## Sub-Header 2\n\n![Description](/image.jpg \"Title\")\n\n## Sub-Header 3\n\n:::tip\nThis is advice.\n:::The filename can contain a prefix to define date or weight variables of the page (used by sortby).
The date prefix is used to set the date of the page, and must be a valid date format (i.e.: « YYYY-MM-DD »).
Example:
\nIn « 2019-04-23_My blog post.md »:
\ndate of the page is « 2019-04-23 »title of the page is « My blog post »The weight prefix is used to set the sort order of the page, and must be a valid integer value.
\nExample:
\nIn « 1_The first project.md »:
\nweight of the page is « 1 »title of the page is « The first project »Some dedicated variables can be used in a custom Section (i.e.: <section>/index.md).
The order of pages in a Section can be changed.
\nAvailable values are:
\ndate: more recent firsttitle: alphabetic orderweight: lightest firstExample:
\n\nsortby: title\nMore options:
\n\nsortby:\n variable: date # \"date\", \"updated\", \"title\" or \"weight\"\n desc_title: false # used with \"date\" or \"updated\" variable value to sort by desc title order if items have the same date\n reverse: false # reversed if true\nThe global pagination configuration is used by default, but you can change it for a specific Section.
\nExample:
\n\npagination:\n max: 5\n path: \"page\"\nPagination can be disabled for a Section:
\n\npagination: false\nAny variables in cascade are added to the front matter of all sub pages.
Example:
\n\ncascade:\n banner: image.jpg\nSet circular to true to enable circular navigation with page.<prev/next>.
Example:
\n\ncircular: true\nA nested folder that explicitly contains an index.md file is turned into a sub-section of its parent Section.
<mywebsite>\n└─ pages\n └─ blog <- Section\n ├─ index.md\n ├─ post-1.md <- Page in Section \"blog\"\n └─ 2024 <- Sub-section (contains an \"index.md\")\n ├─ index.md\n └─ post-2.md <- Page in Section \"blog\" *and* sub-section \"blog/2024\"A sub-section:
\n/blog/2024/)blog/list.html.twig)blog/2024/06/)sortby), followed by its own pagesLike another section, Home page support sortby and pagination configuration.
Set a valid Section name in pagesfrom to use pages collection from this Section in Home page.
Example:
\n\npagesfrom: blog\nCecil renders pages with Twig templates: this page explains how templates are organized and how the right one is chosen for each page.
\nThere are three kinds of templates: layouts, components, and other templates. Layouts are used to render pages, and each layout can include templates and components.
\nTemplate files are stored in the layouts/ directory and must be named according to the following convention:
layouts/(<section>/)<type>|<layout>.<format>(.<language>).twig<section> (optional)blog).<type>home (or index) for homepage, list for list, page for page, etc. (See Lookup rules for details).<layout> (optional)layout: my-layout).<format>html, rss, json, xml, etc.).<language> (optional)fr).Examples:
\nlayouts/home.html.twig # `type` is \"homepage\"\nlayouts/page.html.twig # `type` is \"page\"\nlayouts/page.html.fr.twig # `type` is \"page\" and `language` is \"fr\"\nlayouts/my-layout.html.twig # `layout` is \"my-layout\"\nlayouts/blog/list.html.twig # `section` is \"blog\"\nlayouts/blog/list.rss.twig # `section` is \"blog\" and `format` is \"rss\"<my-site>\n├─ ...\n├─ layouts\n| ├─ index.html.twig # Used by type \"homepage\"\n| ├─ list.html.twig # Used by types \"homepage\" and \"section\"\n| ├─ list.rss.twig # Used by types \"homepage\" and \"section\", for RSS output format\n| ├─ page.html.twig # Used by type \"page\"\n| ├─ taxonomy\n| | ├─ tags.html.twig # Used by type \"vocabulary\" of `tags` (list of terms)\n| | └─ tag.html.twig # Used by type \"term\" of `tags` (list of pages)\n| ├─ my-layout.html.twig # Used by pages with `layout: my-layout` in the front matter\n| ├─ ...\n| └─ partials # Included templates\n| ├─ footer.html.twig\n| └─ ...\n└─ themes # Themes layouts and templates\n └─ ...Cecil comes with a set of built-in templates.
\n\nIn most of cases you don’t need to specify the layout: Cecil selects the most appropriate layout, according to the page type.
\nFor example, the HTML output of home page (index.md) will be rendered:
my-layout.html.twig if the layout variable is set to \"my-layout\" (in the front matter)index.html.twig if the file existshome.html.twig if the file existslist.html.twig if the file existsAll rules are detailed below, for each page type, in the priority order.
\n<layout>.<format>.twigindex.<format>.twighome.<format>.twiglist.<format>.twig_default/<layout>.<format>.twig_default/index.<format>.twig_default/home.<format>.twig_default/list.<format>.twig_default/page.<format>.twig<section>/<layout>.<format>.twig<layout>.<format>.twig<section>/page.<format>.twig_default/<layout>.<format>.twigpage.<format>.twig_default/page.<format>.twig<layout>.<format>.twig<section>/index.<format>.twig<section>/list.<format>.twigsection/<section>.<format>.twig<parent>/index.<format>.twig, <parent>/list.<format>.twig and section/<parent>.<format>.twig, for each parent section of a sub-section (nearest first)_default/section.<format>.twiglist.<format>.twig_default/list.<format>.twigtaxonomy/<plural>.<format>.twigvocabulary.<format>.twig_default/vocabulary.<format>.twigtaxonomy/<plural>/<term>.<format>.twigtaxonomy/<singular>.<format>.twigterm.<format>.twig_default/term.<format>.twig_default/list.<format>.twig\n\nFunctions can be called to generate content. Functions are called by their name followed by parentheses (
\n()) and may have arguments.
Creates a valid URL for a page, a menu entry, an asset, a page ID or a path.
\n{{ url(value, {options}) }}| Option | \nDescription | \nType | \nDefault | \n
|---|---|---|---|
| canonical | \nPrefix URL with baseurl or use canonical.url if exists. | \nboolean | \nfalse | \n
| format | \nDefines page output format (e.g.: json). | \nstring | \nhtml | \n
| language | \nDefines page language (e.g.: fr). | \nstring | \nnull | \n
Examples:
\n{# page #}\n{{ url(page) }}\n{{ url(page, {canonical: true}) }}\n{{ url(page, {format: json}) }}\n{{ url(page, {language: fr}) }}\n{# menu entry #}\n{{ url(site.menus.main.about) }}\n{# asset #}\n{{ url(asset('styles.css')) }}\n{# page ID #}\n{{ url('page-id') }}\n{# path #}\n{{ url('about-me/') }}\n{{ url('tags/' ~ tag) }}Creates an HTML element from an asset (or an array of assets with custom attributes).
\n{{ html(asset, {attributes}, {options}) }}\n{# dedicated functions for each common type of asset #}\n{{ css(asset) }}\n{{ js(asset) }}\n{{ image(asset) }}\n{{ audio(asset) }}\n{{ video(asset) }}| Option | \nDescription | \nType | \n
|---|---|---|
| attributes | \nAdds name=\"value\" couple to the HTML element. | \narray | \n
| options | \n{preload: boolean}: preloads.For images: {formats: array}: adds alternative formats.{responsive: bool|string}: adds responsive images (based on width or pixels density).{placeholder: string}: fills the image background before loading (color or lqip). | \narray | \n
Examples:
\n{# CSS with an attribute #}\n{{ html(asset('print.css'), {media: 'print'}) }}\n{# CSS with an attribute and an option #}\n{{ html(asset('styles.css'), {title: 'Main theme'}, {preload: true}) }}\n{# Array of assets with media query #}\n{{ html([\n {asset: asset('css/style.css')},\n {asset: asset('css/style-dark.css'), attributes: {media: '(prefers-color-scheme: dark)'}}\n]) }}\n{# JavaScript #}\n{{ html(asset('script.js')) }}\n{# image without specific attributes nor options #}\n{{ html(asset('image.png')) }}\n{# image with specific attributes, responsive images and alternative formats #}\n{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {responsive: true, formats: ['avif', 'webp']}) }}\n{# image with responsive pixels density images #}\n{{ html(asset('image.jpg'), options={responsive: 'density'}, attributes={width: 256}) }}\n{# image with a Low-Quality Image Placeholder #}\n{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {placeholder: 'lqip'}) }}\n{# Audio #}\n{{ html(asset('audio.mp3')) }}\n{# Video #}\n{{ html(asset('video.mp4')) }}Determines read time of a text, in minutes.
\n{{ readtime(value) }}Example:
\n{{ readtime(page.content) }} minCalculates the hash of an object, an array or a string with a given algorithm.
\n{{ hash(value, algorithm) }}algorithm can be any algorithm supported by PHP's hash() function (e.g.: md5, sha256, etc.). Default is xxh128.
Example:
\n{{ hash('my string', 'sha256') }}Calculates a cache key for fragments cache based on a name and an optional value.
\n{% cache cache_key(name, value) %}\n {# cacheable content #}\n{% endcache %}The function adds a hash of the value (could be a string, an array or an object) to the name (and the current language and build ID to be sure the generated cache key is unique) so if the value is changed the cache key is changed too and the cache is automatically cleared.
\nGets the value of an environment variable from its key.
\n{{ getenv(var) }}Example:
\n{{ getenv('VAR') }}The dump function dumps information about a template variable. This is mostly useful to debug a template that does not behave as expected by introspecting its variables:
{{ dump(user) }}The d() function is the HTML version of dump() and use the Symfony VarDumper Component behind the scenes.
{{ d(variable, {theme: light}) }}Cecil provides Twig filters to compile Sass, minify, fingerprint, inline or embed CSS and JavaScript assets.
\nAdd the file content finger print to the file name.
\n{{ asset(path)|fingerprint }}\n{{ path|fingerprint }}Examples:
\n{{ asset('styles.css')|fingerprint }}Minifying a CSS or a JavaScript file.
\n{{ asset(path)|minify }}Examples:
\n{{ asset('styles.css')|minify }}\n{{ asset('scripts.js')|minify }}Minifying a CSS string.
\n{{ variable|minify_css }}{% apply minify_css %}\n{# CSS here #}\n{% endapply %}Examples:
\n{% set styles = 'some CSS here' %}\n{{ styles|minify_css }}<style>\n{% apply minify_css %}\n html {\n background-color: #fcfcfc;\n color: #444;\n }\n{% endapply %}\n</style>Minifying a JavaScript string.
\n{{ variable|minify_js }}{% apply minify_js %}\n{# JavaScript here #}\n{% endapply %}Examples:
\n{% set script = 'some JavaScript here' %}\n{{ script|minify_js }}<script>\n{% apply minify_js %}\n var test = 'test';\n console.log(test);\n{% endapply %}\n</script>Compiles a Sass string to CSS.
\n{{ variable|scss_to_css }}{% apply scss_to_css %}\n{# SCSS here #}\n{% endapply %}Alias: sass_to_css.
Examples:
\n{% set scss = 'some SCSS here' %}\n{{ scss|scss_to_css }}<style>\n{% apply scss_to_css %}\n $color: #fcfcfc;\n div {\n color: lighten($color, 20%);\n }\n{% endapply %}\n</style>Compiles a Sass file to CSS.
\n{{ asset(path)|to_css }}\n{{ path|to_css }}Examples:
\n{{ asset('styles.scss')|to_css }}Outputs the content of an Asset.
\n{{ asset(path)|inline }}Example:
\n{{ asset('styles.css')|inline }}Returns the data URL of an asset.
\n{{ asset(path)|dataurl }}\n{{ asset(image_path)|dataurl }}These options define the main language of the site and, for a multilingual website, its additional languages.
\nThe main language, defined by its code.
\nlanguage: <code> # unique code (`en` by default)By default only others languages pages path are prefixed with its language code, but you can prefix the path of the main language pages with the following option:
\n#language: <code>\nlanguage:\n code: <code>\n prefix: trueOptions of available languages, used for pages and templates localization.
\nlanguages:\n - code: <code> # unique code (e.g.: `en`, `fr`, 'en-US', `fr-CA`)\n name: <name> # human readable name (e.g.: `Français`)\n locale: <locale> # locale code (`language_COUNTRY`, e.g.: `en_US`, `fr_FR`, `fr_CA`)\n enabled: <true|false> # enabled or not (`true` by default)Example:
\nlanguage: en\nlanguages:\n - code: en\n name: English\n locale: en_US\n - code: fr\n name: Français\n locale: fr_FRTo localize configuration options you must store them under the config key of the language.
Example:
\ntitle: \"Cecil in english\"\nlanguages:\n - code: en\n name: English\n locale: en_US\n - code: fr\n name: Français\n locale: fr_FR\n config:\n title: \"Cecil en français\"The front matter can contains custom variables applied to the current page.
\nIt must be the first thing in the file and must be a valid YAML.
\n| Variable | \nDescription | \nDefault value | \nExample | \n
|---|---|---|---|
title | \nTitle | \nFile name without extension. | \nPost 1 | \n
layout | \nTemplate | \nSee Lookup rules. | \n404 | \n
date | \nCreation date | \nFile creation date (PHP DateTime object). | \n2019/04/15 | \n
section | \nSection | \nPage's Section. | \nblog | \n
path | \nPath | \nPage's path. | \nblog/post-1 | \n
slug | \nSlug | \nPage's slug. | \npost-1 | \n
published | \nPublished or not | \ntrue. | \nfalse | \n
draft | \nPublished or not | \nfalse. | \ntrue | \n
The updated variable is used to define the last modification date of a page.
Example:
\n\nupdated: 2026-02-02\nA page can be added to a menu.
\nThe entry name is the page title and the URL is the page path.
The same page can be added to multiple menus, and each entry's position can be set with the weight key (lowest first). The name key can be used to override the default entry name per menu.
Examples:
\n\nmenu: main\n\nmenu: [main, navigation] # same page in multiple menus\n\nmenu:\n main:\n weight: 10\n navigation:\n weight: 20\n\ntitle: 'Our Expertise'\nmenu:\n main:\n weight: 15\n footer:\n weight: 15\n name: \"Expertise\" # override the entry name in this menu\nTaxonomy allows you to connect, relate and classify your website’s content.
\nIn Cecil, these terms are gathered within vocabularies.
Vocabularies are declared in the Configuration.
\ntags, categories, etc.).Development, PHP, etc.).Example:
\n\ntags: [\"Development\", \"PHP\"]\nCecil then generates, for each vocabulary:
\n/tags//tags/development/ and /tags/php/See templates lookup rules and taxonomy variables to customize those pages.
\nSchedules pages’ publication.
\nExample:
\nThe page will be published if current date is >= 2023-02-07:
\nschedule:\n publish: 2023-02-07This page is published if current date is <= 2022-04-28:
\nschedule:\n expiry: 2022-04-28As indicated by its name, the redirect variable is used to redirect a page to a dedicated URL.
Example:
\n\nredirect: \"https://arnaudligny.fr\"\nAlias is a redirection to the current page
\nExample:
\n\ntitle: \"About\"\nalias:\n - contact\nIn the previous example contact/ redirects to about/.
Defines the output format of the page.
\nAvailable formats are: html, atom, rss, json, xml, etc.
\nYou can define one or more formats in an array.
I’s not required to define an output format, but if you do, it must be one of the available formats defined in the Configuration.
\nExample:
\n\noutput: [html, atom]\nA page with an external variable try to fetch the content of the pointed resource.
Example:
\n\nexternal: \"https://raw.githubusercontent.com/Cecilapp/Cecil/main/README.md\"\nSet excluded to true to hide a page from list pages (i.e.: Home page, Section, Sitemap, etc.).
Example:
\n\nexcluded: true\n\n\nThe application passes variables to the templates for manipulation in the template. Variables may have attributes or elements you can access, too.
\n
\nUse a dot (.) to access attributes of a variable:{{ foo.bar }}
You can use variables from different scopes: site, page, cecil.
The site variable contains built-in variables and those set in the configuration.
| Variable | \nDescription | \n
|---|---|
site.pages | \nCollection of all pages, in the current language. | \n
site.allpages | \nCollection of all pages, in all languages. | \n
site.page(id) | \nA page with the given ID. | \n
site.taxonomies | \nCollection of vocabularies. | \n
site.home | \nID of the home page. | \n
site.time | \nCurrent Timestamp. | \n
site.debug | \nDebug mode status (true or false). | \n
site.build | \nCurrent build ID. | \n
Example:
\ntitle: \"My amazing website!\"Can be displayed in a template with:
\n{{ site.title }}Loop on site.menus.<menu> to get each entry of the <menu> collection (e.g.: main).
| Variable | \nDescription | \n
|---|---|
<entry>.name | \nEntry name. | \n
<entry>.url | \nEntry URL. | \n
<entry>.weight | \nEntry weight (useful to sort menu entries). | \n
Example:
\n<nav>\n <ol>\n {% for entry in site.menus.main|sort_by_weight %}\n <li><a href=\"{{ url(entry.url) }}\" data-weight=\"{{ entry.weight }}\">{{ entry.name }}</a></li>\n {% endfor %}\n </ol>\n</nav>Information about the current language.
\n| Variable | \nDescription | \n
|---|---|
site.language | \nLanguage code (e.g.: en). | \n
site.language.name | \nLanguage name (e.g.: English). | \n
site.language.locale | \nLanguage locale code (e.g.: en_US). | \n
site.language.weight | \nLanguage position in the languages list. | \n
The static files collection can be accessed via site.static if the static load is enabled.
Each file exposes the following properties:
\npath: relative path (e.g.: /images/img-1.jpg)date: creation date (timestamp)updated: modification date (timestamp)name: name (e.g.: img-1.jpg)basename: name without extension (e.g.: img-1)ext: extension (e.g.: jpg)type: media type (e.g.: image)subtype: media sub type (e.g.: image/jpeg)exif: image EXIF data (array)audio: Mp3Info objectvideo: array of basic video information (duration in seconds, width and height)A data collection can be accessed via site.data.<filename> (without file extension).
Examples:
\ndata/authors.yml : site.data.authorsdata/authors.fr.yml : site.data.authors (if site.language = \"fr\")data/galleries/gallery-1.json : site.data.galleries['gallery-1']The page variable contains built-in variables of a page and those set in the front matter.
| Variable | \nDescription | \nExample | \n
|---|---|---|
page.id | \nUnique identifier. | \nblog/post-1 | \n
page.title | \nFile name (without extension). | \nPost 1 | \n
page.date | \nFile creation date. | \nDateTime | \n
page.body | \nFile body. | \nMarkdown | \n
page.content | \nFile body converted in HTML. | \nHTML | \n
page.section | \nFile root folder (slugified). | \nblog | \n
page.path | \nFile path (slugified). | \nblog/post-1 | \n
page.slug | \nFile name (slugified). | \npost-1 | \n
page.filepath | \nFile system path. | \nBlog/Post 1.md | \n
page.type | \nhomepage, page, section, vocabulary or term. | \npage | \n
page.pages | \nCollection of all sub pages. | \nCollection | \n
page.translations | \nCollection of translated pages. | \nCollection | \n
In a nested sections context, page.parent, page.ancestors, page.sections and page.toplevel help you build navigation.
| Variable | \nDescription | \nExample | \n
|---|---|---|
page.parent | \nParent section's page (null if none). | \nPage | \n
page.ancestors | \nCollection of ancestor sections (nearest first). | \nCollection | \n
page.sections | \nCollection of immediate descendant sections. | \nCollection | \n
page.toplevel | \ntrue if the page is a top level section. | \nBoolean | \n
Breadcrumb (from the home page to the current page):
\n<nav aria-label=\"breadcrumb\">\n <ul>\n <li><a href=\"{{ url(site.home) }}\">{{ site.title }}</a></li>\n {% for section in page.ancestors|reverse %}\n <li><a href=\"{{ url(section) }}\">{{ section.title }}</a></li>\n {% endfor %}\n {% if page.id != site.home %}\n <li><a href=\"{{ url(page) }}\" aria-current=\"page\">{{ page.title }}</a></li>\n {% endif %}\n </ul>\n</nav>Sub-sections menu (immediate descendant sections of the current section):
\n{% if page.sections|length %}\n<ul>\n {% for section in page.sections|sort_by_title %}\n <li><a href=\"{{ url(section) }}\">{{ section.title }}</a></li>\n {% endfor %}\n</ul>\n{% endif %}Main navigation limited to top level sections (from any page):
\n<nav>\n {% for section in site.page(site.home).sections|sort_by_title %}\n <a href=\"{{ url(section) }}\">{{ section.title }}</a>\n {% endfor %}\n</nav>Link to the parent section:
\n{% if page.parent %}\n<a href=\"{{ url(page.parent) }}\">← {{ page.parent.title }}</a>\n{% endif %}Navigation between pages within the same section, sorted according to the section's sortby (chronological order for dates).
With sub-sections, navigation follows the sections tree: the pages of a top level Section and of all its sub-sections are chained, each sub-section (its index page) being placed among the pages of its parent Section and followed by its own pages.
\n| Variable | \nDescription | \nExample | \n
|---|---|---|
page.prev | \nPrevious page. | \nPage | \n
page.next | \nNext page. | \nPage | \n
Example:
\n<a href=\"{{ url(page.prev) }}\">{{ page.prev.title }}</a>Paginator helps you build navigation for list pages: homepage, sections, and taxonomies.
\n| Variable | \nDescription | \n
|---|---|
page.paginator.pages | \nPages Collection. | \n
page.paginator.pages_total | \nNumber total of pages. | \n
page.paginator.count | \nNumber of paginator's pages. | \n
page.paginator.current | \nPosition index of the current page. | \n
page.paginator.links.first | \nPage ID of the first page. | \n
page.paginator.links.prev | \nPage ID of the previous page. | \n
page.paginator.links.self | \nPage ID of the current page. | \n
page.paginator.links.next | \nPage ID of the next page. | \n
page.paginator.links.last | \nPage ID of the last page. | \n
page.paginator.links.path | \nPage ID without the position index. | \n
Example:
\n{% if page.paginator %}\n<div>\n {% if page.paginator.links.prev is defined %}\n <a href=\"{{ url(page.paginator.links.prev) }}\">Previous</a>\n {% endif %}\n {% if page.paginator.links.next is defined %}\n <a href=\"{{ url(page.paginator.links.next) }}\">Next</a>\n {% endif %}\n</div>\n{% endif %}Example:
\n{% if page.paginator %}\n<div>\n {% for paginator_index in 1..page.paginator.count %}\n {% if paginator_index != page.paginator.current %}\n {% if paginator_index == 1 %}\n <a href=\"{{ url(page.paginator.links.first) }}\">{{ paginator_index }}</a>\n {% else %}\n <a href=\"{{ url(page.paginator.links.path ~ '/' ~ paginator_index) }}\">{{ paginator_index }}</a>\n {% endif %}\n {% else %}\n {{ paginator_index }}\n {% endif %}\n {% endfor %}\n</div>\n{% endif %}Variables available in vocabulary and term templates.
\nPage /<plural>/ (e.g.: /categories/).
| Variable | \nDescription | \n
|---|---|
page.plural | \nVocabulary name in plural form. | \n
page.singular | \nVocabulary name in singular form. | \n
page.terms | \nList of terms (Collection). | \n
Each term of page.terms provides term.id (term ID, e.g.: categories/php), term.name (term name, e.g.: PHP) and the number of its pages with term|length.
Page /<plural>/<term>/ (e.g.: /categories/php/).
| Variable | \nDescription | \n
|---|---|
page.title | \nTerm name. | \n
page.term | \nTerm ID (e.g.: categories/php). | \n
page.plural | \nVocabulary name in plural form. | \n
page.singular | \nVocabulary name in singular form. | \n
page.pages | \nList of pages in this term, sorted by date (Collection). | \n
Configuration:
\ntaxonomies:\n categories: categoryPage front matter:
\n\ncategories: [\"Data Sovereignty\"]\nList of terms (/categories/), in layouts/taxonomy/categories.html.twig:
{% extends 'page.html.twig' %}\n\n{% block content %}\n <h1>{{ page.title }}</h1>\n <ul>\n {% for term in page.terms %}\n <li><a href=\"{{ url(term.id) }}\">{{ term.name }}</a> ({{ term|length }})</li>\n {% endfor %}\n </ul>\n{% endblock %}List of pages of a term (/categories/data-sovereignty/), in layouts/taxonomy/category.html.twig:
{% extends 'page.html.twig' %}\n\n{% block content %}\n <h1>{{ page.title }}</h1>\n {% for p in page.paginator.pages ?? page.pages %}\n <article>\n <h2><a href=\"{{ url(p) }}\">{{ p.title }}</a></h2>\n </article>\n {% endfor %}\n <a href=\"{{ url(page.plural) }}\">All {{ page.plural }}</a>\n{% endblock %}Links to the terms of the current page, in a page template:
\n{% for category in page.categories ?? [] %}\n <a href=\"{{ url('categories/' ~ category) }}\">{{ category }}</a>\n{% endfor %}| Variable | \nDescription | \n
|---|---|
cecil.url | \nURL of the Cecil website. | \n
cecil.version | \nCecil current version. | \n
cecil.poweredby | \nPrint Cecil v%s, with %s is the current version. | \n
Sorting collections (of pages, menus or taxonomies).
\nSorts a collection by title (with natural sort).
\n{{ collection|sort_by_title }}Example:
\n{{ site.pages|sort_by_title }}Sorts a collection by date (most recent first).
\n{{ collection|sort_by_date(variable='date', desc_title=false) }}Example:
\n{# sort by date #}\n{{ site.pages|sort_by_date }}\n{# sort by updated variable instead of date #}\n{{ site.pages|sort_by_date(variable='updated') }}\n{# sort items with the same date by desc title #}\n{{ site.pages|sort_by_date(desc_title=true) }}\n{# reverse sort #}\n{{ site.pages|sort_by_date|reverse }}Sorts a collection by weight (lighter first).
\n{{ collection|sort_by_weight }}Example:
\n{{ site.menus.main|sort_by_weight }}For more complex cases, you should use Twig’s native sort.
Example:
\n{% set files = site.static|sort((a, b) => a.date|date('U') < b.date|date('U')) %}Cecil supports Markdown format, but also Markdown Extra.
\nCecil also provides extra features to enhance your content, see below.
\nWith Markdown Extra you can set an id, class and custom attributes on certain elements using an attribute block.
\nFor instance, put the desired attribute(s) after a header, a fenced code block, a link or an image at the end of the line inside curly brackets, like this:
## Header {#id .class attribute=value}You can create a link with the syntax [Text](url), where url can be a path, a relative path to a Markdown file, an external URL, etc.
Example:
\n[Link to a path](/about/)\n[Link to a Markdown file](/about/)\n[Link to Cecil website](https://cecil.app)You can easily create a link to a page with the syntax [Page title](page:page-id).
Example:
\n[Link to a blog post](page:blog/post-1)By default external links have the following value for rel attribute: noopener noreferrer.
Example:
\n<a href=\"<url>\" rel=\"noopener noreferrer\">Link to another website</a>You can change this behavior with pages.body.links.external options.
Cecil can try to turn a link into embedded content by using the {embed} attribute or by setting the global configuration option pages.body.links.embed.enabled to true.
Example:
\n[CECIL : LE générateur de SITES STATIQUES en PHP](https://www.youtube.com/watch?v=ur8koU0iYvc){embed}Cecil can also create a video and audio HTML elements, through the file extension.
\nExample:
\n[Video file](video.mp4){embed controls poster=/images/video-test.png}\n[Audio file](song.mp3){embed controls}Is converted to:
\n<video src=\"/video.mp4\" controls poster=\"/images/video-test.png\" style=\"max-width:100%;height:auto;\"></video>\n<audio src=\"/song.mp3\" controls></audio>With {embed=false} (or when embedding is disabled), a local video/audio file stays a link, but its URL points to the published file (fingerprinted if assets.fingerprint is enabled).
To add an image, use an exclamation mark (!) followed by alternative description in brackets ([]), and the path or URL to the image in parentheses (()).
\nYou can optionally add a title in quotation marks.
![Alternative description](/image.jpg \"Image title\")Cecil adds the attribute loading=\"lazy\" to each image.
Example:
\nIs converted to:
\n<img src=\"/image.jpg\" loading=\"lazy\">Cecil adds the attribute decoding=\"async\" to each image.
Example:
\nIs converted to:
\n<img src=\"/image.jpg\" decoding=\"async\">Each image in the body can be resized automatically by setting a smaller width than the original one, with the extra attribute {width=X}.
Example:
\n{width=800}Is converted to:
\n<img src=\"/thumbnails/800/image.jpg\" width=\"800\" height=\"600\">If the formats option is defined, alternatives images are created and added.
Example:
\nCould be converted to:
\n<picture>\n <source srcset=\"/image.avif\" type=\"image/avif\">\n <source srcset=\"/image.webp\" type=\"image/webp\">\n <img src=\"/image.jpg\">\n</picture>If the responsive option is enabled, then all images in the body will be made responsive automatically.
Example:
\n{width=800}will be converted to:
\n<img src=\"/thumbnails/800/image.jpg\" width=\"800\" height=\"600\"\n srcset=\"/thumbnails/320/image.jpg 320w,\n /thumbnails/640/image.jpg 640w,\n /thumbnails/800/image.jpg 800w\"\n sizes=\"100vw\"\n>The sizes attribute takes the value of the assets.images.responsive.sizes.default configuration option, but it can be changed by creating a new entry named after a class added to the image.
Example:
\nassets:\n images:\n responsive:\n sizes:\n default: 100vw\n my_class: \"(max-width: 800px) 768px, 1024px\"{.my_class}You can set a default value to the class attribute of each image with the class option.
The optional title can be used to create a caption (figcaption) automatically by enabling the caption option.
Example:
\n![](/images/img.jpg \"Title\")Is converted to:
\n<figure>\n <img src=\"/image.jpg\" title=\"Title\">\n <figcaption>Title</figcaption>\n</figure>For translated pages, Cecil first looks for a language-suffixed file when resolving Markdown image paths.
\nExample:
\nWith a French page (fr), Cecil tries /images/cecil-logo.fr.png first, then falls back to /images/cecil-logo.png.
As images are typically heavier and slower resources, and they don’t block rendering, we should attempt to give users something to look at while they wait for the image to arrive.
\nThe placeholder attribute accepts two options:
color: display a colored background (based on image dominant color)lqip: Low-Quality Image PlaceholderExamples:
\n{placeholder=color}\n{placeholder=lqip}You can add a table of contents with the following Markdown syntax:
\n[toc]An excerpt can be defined in the body with one of those following tags: excerpt or break.
Example:
\nIntroduction.\n<!-- excerpt -->\nMain content.Then use the excerpt_html filter in your template.
Create a Note block (info, tips, important, etc.).
\nExample:
\n:::tip\n**Tip:** This is advice.\n:::Is converted to:
\n<aside class=\"note note-tip\">\n <p>\n <strong>Tip:</strong> This is advice.\n </p>\n</aside>Others examples:
\n\n\n\n\n\n\nCode block syntax highlighting is enabled by default with the pages.body.highlight option.
\nIf needed, you can disable it with:
\npages:\n body:\n highlight: falseExample:
\n\n```php\necho \"Hello world\";\n```\n\n
Is rendered to:
\necho \"Hello world\";Represents a range of text that has been added.
\n++text++Is converted to:
\n<ins>text</ins>This page describes how a Cecil project is organized, what the built website looks like and how files are routed to URLs.
\nProject files organization.
\n<mywebsite>\n├─ pages\n| ├─ blog <- Section\n| | ├─ post-1.md <- Page in Section\n| | └─ post-2.md\n| ├─ projects\n| | └─ project-a.md\n| └─ about.md <- Root page\n├─ assets\n| ├─ styles.scss <- Asset file\n| └─ logo.png\n├─ static\n| └─ file.pdf <- Static file\n└─ data\n └─ authors.yml <- Data collectionResult of the build.
\n<mywebsite>\n└─ _site\n ├─ index.html <- Generated home page\n ├─ blog/\n | ├─ index.html <- Generated list of posts\n | ├─ post-1/index.html <- A blog post\n | └─ post-2/index.html\n ├─ projects/\n | ├─ index.html\n | └─ project-a/index.html\n ├─ about/index.html\n ├─ styles.css\n ├─ logo.png\n └─ file.pdfMarkdown files in the pages directory enable file based routing. Meaning that adding a pages/my-projects/project-a.md for instance will make it available at /project-a in your browser.
File:\n pages/my-projects/project-a.md\n └───── filepath ──────┘\nURL:\n ┌───── baseurl ─────┬─────── path ────────┐\n https://example.com/my-projects/project-a/index.html\n └─ section ─┴─ slug ──┘Variables can be modified by filters. Filters are separated from the variable by a pipe symbol (|). Multiple filters can be chained. The output of one filter is applied to the next.
{{ page.title|truncate(25)|capitalize }}Filters a pages collection by variable name/value.
\n{{ collection|filter_by(variable, value) }}Example:
\n{{ pages|filter_by('section', 'blog') }}For more complex cases, you should use Twig’s native filter.
Example:
\n{% pages|filter(p => p.virtual == false and p.id not in ['page-1', 'page-2']) %}Converts a Markdown string to HTML.
\n{{ markdown|markdown_to_html }}{% apply markdown_to_html %}\n{# Markdown here #}\n{% endapply %}Examples:
\n{% set markdown = '**This is bold text**' %}\n{{ markdown|markdown_to_html }}{% apply markdown_to_html %}\n**This is bold text**\n{% endapply %}Extracts only headings matching the given selectors (h2, h3, etc.), or those defined in config pages.body.toc if not specified.
\nThe format parameter defines the output format: html or json.
\nThe url parameter is used to build links to headings.
{{ markdown|toc(format, selectors, url) }}Examples:
\n{{ page.body|toc }}\n{{ page.body|toc('html') }}\n{{ page.body|toc(selectors=['h2']) }}\n{{ page.body|toc(url=url(page)) }}Converts a JSON string to an array.
\n{{ json|json_decode }}Example:
\n{% set json = '{\"foo\": \"bar\"}' %}\n{% set array = json|json_decode %}\n{{ array.foo }}Converts a YAML string to an array.
\n{{ yaml|yaml_parse }}Example:
\n{% set yaml = 'key: value' %}\n{% set array = yaml|yaml_parse %}\n{{ array.key }}Converts a string to a slug.
\n{{ string|slugify }}The u filter wraps a text in a Unicode object (a Symfony UnicodeString instance) that exposes methods to \"manipulate\" the string.
Example:
\n{{ 'cecil_string with twig'|u.camel.title }}\n\nCecilStringWithTwig
\n
The singular filter transforms a given noun in its plural form into its singular version.
{{ string|singular(locale)}}Example:
\n{# English (en) rules are used by default #}\n{{ 'partitions'|singular }}\n\npartition
\n
{{ 'partitions'|singular('fr') }}\n\npartition
\n
The plural filter transforms a given noun in its singular form into its plural version.
{{ string|plural(locale)}}Example:
\n{# English (en) rules are used by default #}\n{{ 'animal'|plural }}\n\nanimals
\n
{{ 'animal'|plural('fr') }}\n\nanimaux
\n
Truncates a string and appends suffix.
\n{{ string|excerpt(length, suffix) }}| Option | \nDescription | \nType | \nDefault | \n
|---|---|---|---|
| length | \nTruncates after this number of characters. | \ninteger | \n450 | \n
| suffix | \nAppends characters. | \nstring | \n… | \n
Examples:
\n{{ variable|excerpt }}\n{{ variable|excerpt(250, '...') }}Reads characters before or after <!-- excerpt --> or <!-- break --> tag.
\nSee Content documentation for details.
{{ string|excerpt_html({separator, capture}) }}| Option | \nDescription | \nType | \nDefault | \n
|---|---|---|---|
| separator | \nString to use as separator. | \nstring | \nexcerpt|break | \n
| capture | \nPart to capture, before or after the separator. | \nstring | \nbefore | \n
Examples:
\n{{ variable|excerpt_html }}\n{{ variable|excerpt_html({separator: 'excerpt|break', capture: 'before'}) }}\n{{ variable|excerpt_html({capture: 'after'}) }}Highlights a code string with highlight.php.
\n{{ code|highlight(language) }}Examples:
\n{{ '<?php echo $highlighted->value; ?>'|highlight('php') }}Splits a string into an array using a regular expression.
\n{{ string|preg_split(pattern, limit) }}Example:
\n{% set headers = page.content|preg_split('/<br[^>]*>/') %}Performs a regular expression match and return the group for all matches.
\n{{ string|preg_match_all(pattern, group) }}Example:
\n{% set tags = page.content|preg_match_all('/<[^>]+>(.*)<\\/[^>]+>/') %}Converts a hexadecimal color to RGB.
\n{{ color|hex_to_rgb }}These options control how pages are loaded, sorted, paginated, routed and generated.
\nDirectory source of pages (pages by default).
pages:\n dir: pagesExtensions of pages files.
\npages:\n ext: [md, markdown, mdown, mkdn, mkd, text, txt]Directories, paths and files name to exclude (accepts globs, strings and regexes).
\npages:\n exclude: ['vendor', 'node_modules', '*.scss', '/\\.bck$/']List of characters used as separator between a filename prefix (date or weight) and the slug.
pages:\n prefix:\n separator: ['-', '_']Default collections sort method.
\npages:\n sortby: date # `date`, `updated`, `title` or `weight`\n # or\n sortby:\n variable: date # `date`, `updated`, `title` or `weight`\n desc_title: false # sort by title in descending order\n reverse: false # reverse the sort orderPagination is available for list pages (type is homepage, section or term).
pages:\n pagination:\n max: 5 # maximum number of entries per page\n path: page # path to the paginated pagePagination can be disabled:
\npages:\n pagination: falseApply a custom path for all pages of a Section.
pages:\n paths:\n - section: <section’s ID>\n path: <path of pages>:year:month:day:section:slugExample:
\npages:\n paths:\n - section: Blog\n path: :section/:year/:month/:day/:slug # e.g.: /blog/2020/12/01/my-post/\n# localized\nlanguages:\n - code: fr\n name: Français\n locale: fr_FR\n config:\n pages:\n paths:\n - section: Blog\n path: blogue/:year/:month/:day/:slug # e.g.: /blogue/2020/12/01/mon-billet/Page front matter format (yaml by default, also accepts ini, toml and json).
pages:\n frontmatter: yamlPage body options.
\n\nHeaders used to build the table of contents ([h2, h3] by default).
pages:\n body:\n toc: [h2, h3]Enables code syntax highlighting (true by default).
pages:\n body:\n highlight: false # set to false to disable syntax highlightingImages handling options.
\npages:\n body:\n images:\n formats: [] # adds alternative image formats as `source` (e.g. `[avif, webp]`, empty array by default)\n resize: 0 # resizes all images to <width> (in pixels, `0` to disable)\n responsive: false # adds responsive image variants to the `srcset` attribute (`false` by default)\n lazy: true # adds `loading=\"lazy\"` attribute (`true` by default)\n decoding: true # adds `decoding=\"async\"` attribute (`true` by default)\n caption: false # puts the image in a <figure> element and adds a <figcaption> containing the title (`false` by default)\n placeholder: '' # fills the <img> background before loading ('color' or 'lqip', empty by default)\n class: '' # sets a default class on each image (empty by default)\n dark_suffix: '' # suffix of the dark variant image (e.g. `.dark`), disabled by default\n mobile_suffix: '' # suffix of the mobile variant image (e.g. `.mobile`), disabled by default\n mobile_media_query: '(max-width: 767px)' # media query of the mobile variant `<source>`\n remote: # remote image handling (set to `false` to disable)\n fallback: # path to the fallback image, stored in assets dir (empty by default)Links handling options.
\npages:\n body:\n links:\n embed:\n enabled: false # turns links in embedded content if possible (`false` by default)\n video: [mp4, webm] # video files extensions\n audio: [mp3] # audio files extensions\n external:\n blank: false # if true open external link in new tab\n noopener: true # if true add \"noopener\" to `rel` attribute\n noreferrer: true # if true add \"noreferrer\" to `rel` attribute\n nofollow: false # if true add \"nofollow\" to `rel` attributeExcerpt handling options.
\npages:\n body:\n excerpt:\n separator: excerpt|break # string to use as separator (`excerpt|break` by default)\n capture: before # part to capture, `before` or `after` the separator (`before` by default)Virtual pages is the best way to create pages without content (front matter only).
\nIt consists of a list of pages with a path and some front matter variables.
Example:
\npages:\n virtual:\n - path: code\n redirect: https://github.com/ArnaudLignyDefault pages are pages created automatically by Cecil (from built-in templates):
\npages:\n default:\n index:\n path: ''\n title: Home\n published: true\n 404:\n path: 404\n title: Page not found\n layout: 404\n uglyurl: true\n published: true\n excluded: true\n robots:\n path: robots\n title: Robots.txt\n layout: robots\n output: txt\n published: true\n excluded: true\n multilingual: false\n sitemap:\n path: sitemap\n title: XML sitemap\n layout: sitemap\n output: xml\n changefreq: monthly\n priority: 0.5\n published: true\n excluded: true\n multilingual: false\n xsl/atom:\n path: xsl/atom\n layout: feed\n output: xsl\n uglyurl: true\n published: true\n excluded: true\n xsl/rss:\n path: xsl/rss\n layout: feed\n output: xsl\n uglyurl: true\n published: false\n excluded: trueEach one can be:
\npublished: falseexcluded: truemultilingual: falseGenerators are used by Cecil to create additional pages (e.g.: sitemap, feed, pagination, etc.) from existing pages, or from other sources like the configuration file or external sources.
\nBelow the list of Generators provided by Cecil, in a defined order:
\npages:\n generators:\n 10: 'Cecil\\Generator\\DefaultPages'\n 20: 'Cecil\\Generator\\VirtualPages'\n 30: 'Cecil\\Generator\\ExternalBody'\n 40: 'Cecil\\Generator\\Section'\n 50: 'Cecil\\Generator\\Taxonomy'\n 60: 'Cecil\\Generator\\Homepage'\n 70: 'Cecil\\Generator\\Pagination'\n 80: 'Cecil\\Generator\\Alias'\n 90: 'Cecil\\Generator\\Redirect'Subsets are used to render a part of the pages collection, based on a specific path, language or output format, with the command:
\ncecil build --render-subset=<name>pages:\n subsets:\n <name>:\n path: <path> # glob or string path (e.g.: `blog/*`, `blog`)\n language: <language> # language code (e.g.: `en`, `fr`)\n output: <output> # output format (e.g.: `html`, `atom`)Example:
\npages:\n subsets:\n blog_en:\n path: blog\n language: en\n output: html\n search_index:\n path: '*'\n output: jsonIf your pages are available in multiple languages there is 2 different ways to define it:
\nThis is the common way to translate a page from the main language to another language.
\nYou just need to duplicate the reference page and suffix it with the target language code (e.g.: fr).
Example:
\n├─ about.md # the reference page\n└─ about.fr.md # the french version (`fr`)If you want to create a page in a language other than the main language, without it being a translation of an existing page, you can use the language variable in its front matter.
Example:
\n\nlanguage: fr\nEach translated page reference the pages in others languages.
\nThose pages collection is available in templates with the following variable:
\n{{ page.translations }}Cecil provides a components logic to give you the power making reusable template \"units\".
\n\nComponents are just Twig templates stored in the components/ subdirectory and can be used anywhere in your templates:
{# /components/button.twig #}\n<button {{ attributes.merge({class: 'rounded px-4'}) }}>\n {{ slot }}\n</button>\n\nThe slot variable is any content you will add between the opening and the close tag.
\n
To reach a component you need to use the dedicated tag x followed by : and the filename of your component without extension:
{# /index.twig #}\n{% x:button with {class: 'text-white'} %}\n <strong>Click me</strong>\n{% endx %}It will render:
\n<button class=\"text-white rounded px-4\">\n <strong>Click me</strong>\n</button>These options define where data files and static files are stored and how they are handled.
\nWhere data files are stored and what extensions are handled.
\nSupported formats: YAML, JSON, XML and CSV.
\nData source directory (data by default).
data:\n dir: dataArray of files extensions.
\ndata:\n ext: [yaml, yml, json, xml, csv]Enables site.data collection (true by default).
data:\n load: trueManagement of static files are copied (PDF, fonts, etc.).
\n\nStatic files source directory (static by default).
static:\n dir: staticDirectory where static files are copied (root by default).
\nstatic:\n target: ''List of excluded files. Accepts globs, strings and regexes.
\nstatic:\n exclude: ['sass', 'scss', '*.scss', 'package*.json', 'node_modules']Enables site.static collection (false by default).
static:\n load: falseAllows to copy specific files or directories to a specific destination.
\nstatic:\n mounts: []static:\n dir: docs\n target: docs\n exclude: ['sass', '*.scss', '/\\.bck$/']\n load: true\n mounts:\n - source/path/file.ext: dest/path/file.ext\n - node_modules/bootstrap-icons/font/fonts: fontsBy default, the body of a page is static: Twig syntax written in a Markdown file is output as is.
\nYou can create dynamic content in a page by using the template_from_string Twig function, which renders the page content as a Twig template.
{{ include(template_from_string(page.content, \"dynamic content for page \" ~ page.id)) }}With this, you can use any page variable in the body of the page.
\n---\nvar: 'value'\n---\nThe value of `var` is {{ page.var }}.The recommended way is to create a dedicated layout that overrides the content block, and to use it only for pages that need it.
{# layouts/dynamic.html.twig #}\n{% extends '_default/page.html.twig' %}\n\n{% block content %}\n{{ include(template_from_string(page.content, \"dynamic content for page \" ~ page.id)) }}\n{% endblock content %}Then set the layout variable in the front matter of the page:
\ntitle: \"My dynamic page\"\nlayout: dynamic\nThe page content is rendered with the same context as the layout, so you can use:
\npage.title, page.date, page.<custom variable>, etc.site.title, site.pages, site.data, etc.{% set %}, {% if %}, {% for %}, {% include %}, etc.The Markdown body is converted to HTML first, then the result (page.content) is rendered by Twig. This order has some consequences:
< and > characters, so comparison operators (>, <=) and arrow functions (=>) can’t be used in the body: the build fails with an Unexpected character \"&\" error.href=\"{{ url(post) }}\") is URL encoded by the Markdown converter and won’t be evaluated.<p> element.To display Twig syntax as is, wrap it in a verbatim tag:
{% verbatim %}`{{ page.title }}`{% endverbatim %}To avoid an extra <p> element around a block of HTML, wrap the expression in an HTML element, separated by line breaks:
<div>\n{{ include('partials/latest-posts.html.twig') }}\n</div>This example shows a page displaying site and page variables, data from a data file, and the latest blog posts through a reusable partial template.
\nData file:
\n# data/team.yml\n- name: Alice\n role: Developer\n- name: Bob\n role: DesignerPartial template, which receives section and limit as parameters:
{# layouts/partials/latest-posts.html.twig #}\n{% set posts = site.pages.showable|filter_by('section', section|default('blog'))|sort_by_date|slice(0, limit|default(5)) %}\n{% if posts|length > 0 %}\n<ul class=\"latest-posts\">\n {% for post in posts %}\n <li><a href=\"{{ url(post) }}\">{{ post.title }}</a> <time datetime=\"{{ post.date|date('Y-m-d') }}\">{{ post.date|format_date('long') }}</time></li>\n {% endfor %}\n</ul>\n{% else %}\n<p>No posts yet.</p>\n{% endif %}Page:
\n---\ntitle: About\nlayout: dynamic\n---\nWelcome to **{{ site.title }}**! This page was published on {{ page.date|format_date('long') }}.\n\nOur team has {{ site.data.team|length }} members: {{ site.data.team|column('name')|join(', ') }}.\n\n## Latest posts\n\n<div>\n{{ include('partials/latest-posts.html.twig', {section: 'blog', limit: 3}) }}\n</div>Output:
\n<p>Welcome to <strong>My site</strong>! This page was published on October 9, 2026.</p>\n<p>Our team has 2 members: Alice, Bob.</p>\n<h2 id=\"latest-posts\">Latest posts</h2>\n<div>\n<ul class=\"latest-posts\">\n <li><a href=\"/blog/post-3/\">Post 3</a> <time datetime=\"2026-03-01\">March 1, 2026</time></li>\n <li><a href=\"/blog/post-2/\">Post 2</a> <time datetime=\"2026-02-01\">February 1, 2026</time></li>\n <li><a href=\"/blog/post-1/\">Post 1</a> <time datetime=\"2026-01-01\">January 1, 2026</time></li>\n</ul>\n</div>Twig macros can be used as shortcodes to insert rich HTML snippets in the body of a page.
\nCreate the macros:
\n{# layouts/macros/shortcodes.html.twig #}\n{% macro youtube(id, title = 'YouTube video') %}\n<iframe src=\"https://www.youtube-nocookie.com/embed/{{ id }}\" title=\"{{ title }}\" width=\"560\" height=\"315\" loading=\"lazy\" allowfullscreen></iframe>\n{% endmacro %}\n\n{% macro alert(message, type = 'info') %}\n<div class=\"alert alert-{{ type }}\" role=\"alert\">{{ message }}</div>\n{% endmacro %}Create a layout that imports the macros before rendering the content:
\n{# layouts/shortcodes.html.twig #}\n{% extends '_default/page.html.twig' %}\n\n{% block content %}\n{% set imports = \"{% import 'macros/shortcodes.html.twig' as sc %}\" %}\n{{ include(template_from_string(imports ~ page.content, \"dynamic content for page \" ~ page.id)) }}\n{% endblock content %}Use the shortcodes in a page:
\n---\ntitle: \"Demo video\"\nlayout: shortcodes\n---\n<div>\n {{ sc.alert('This video is in English.', 'warning') }}\n</div>\n\n## Demo\n\n<div>\n{{ sc.youtube('NaB8JBfE7DY', 'Cecil demo') }}\n</div>Output:
\n<div>\n <div class=\"alert alert-warning\" role=\"alert\">This video is in English.</div>\n</div>\n<h2 id=\"demo\">Demo</h2>\n<div>\n <iframe src=\"https://www.youtube-nocookie.com/embed/NaB8JBfE7DY\" title=\"Cecil demo\" width=\"560\" height=\"315\" loading=\"lazy\" allowfullscreen></iframe>\n</div>Cecil support text translation and date localization.
\nUses the trans tag or filter to translate texts in templates.
{% trans with variables into locale %}{% endtrans %}{{ message|trans(variables = []) }}{% trans %}Hello World!{% endtrans %}{{ message|trans }}Include variables:
\n{% trans with {'%name%': 'Arnaud'} %}Hello %name%!{% endtrans %}{{ message|trans({'%name%': 'Arnaud'}) }}Force locale:
\n{% trans into 'fr_FR' %}Hello World!{% endtrans %}Pluralize:
\n{% trans with {'%count%': 42}%}{0}I don't have apples|{1}I have one apple|]1,Inf[I have %count% apples{% endtrans %}Translation files must be named messages.<locale>.<extension> and stored in the translations directory.
\nSupported file extensions are defined by each translation format in layouts.translations.formats.
The locale code (e.g.: fr_FR) of a language is defined in the languages entries of the configuration.
Example:
\n<mywebsite>\n└─ translations\n ├─ messages.fr_FR.mo <- Machine Object format\n └─ messages.fr_FR.yaml <- Yaml formatUses the Twig format_date filter to localize a date in templates.
{{ page.date|format_date('long') }}\n{# September 30, 2022 #}Supported values are: short, medium, long, and full.
Assets management (images, CSS and JS files).
\nAssets source directory (assets by default).
assets:\n dir: assetsDirectory where remote and resized assets files are saved (root by default).
\nassets:\n target: ''Enables fingerprinting (cache busting) for assets files (true by default).
assets:\n fingerprint: trueEnables Sass files compilation (true by default). See the documentation of scssphp for options details.
assets:\n compile:\n style: expanded # compilation style (`expanded` or `compressed`. `expanded` by default)\n import: [sass, scss] # list of imported paths (`[sass, scss, node_modules]` by default)\n sourcemap: false # enables sourcemap in debug mode (`false` by default)\n variables: [] # list of preset variables (empty by default)Enables CSS and JS minification (true by default).
assets:\n minify: trueImages management.
\nassets:\n images:\n optimize: false # enables images optimization with JpegOptim, Optipng, Pngquant 2, SVGO 1, Gifsicle, cwebp, avifenc (`false` by default)\n quality: 75 # image quality of `optimize` and `resize` (`75` by default)\n responsive:\n widths: [480, 640, 768, 1024, 1366, 1600, 1920] # `srcset` attribute images widths\n sizes:\n default: '100vw' # default `sizes` attribute (`100vw` by default)URL of image assets can be easily replaced by a provided CDN url.
assets:\n images:\n cdn:\n enabled: false # enables Image CDN (`false` by default)\n canonical: true # `image_url` is canonical (instead of a relative path) (`true` by default)\n remote: true # handles not local images too (`true` by default)\n account: 'xxxx' # provider account\n url: 'https://provider.tld/%account%/%image_url%?w=%width%&q=%quality%&format=%format%'url is a pattern that contains variables:
%account% replaced by the assets.images.cdn.account option%image_url% replaced by the image canonical URL or path%width% replaced by the image width%quality% replaced by the assets.images.quality option%format% replaced by the image formatSee CDN providers.
\nUser agent used to download remote assets.
\nassets:\n remote:\n useragent:\n default: <string> # default user agent\n useragent1: <string>\n useragent2: <string>Cecil uses a cache system to speed up the generation process, it can be disabled or cleared.
\nThere are three cache types involved in template rendering: templates, assets, and translations.
\nYou can clear the cache with the following commands:
\nphp cecil.phar cache:clear # clear all caches\nphp cecil.phar cache:clear:assets # clear assets cache\nphp cecil.phar cache:clear:templates # clear templates cache\nphp cecil.phar cache:clear:translations # clear translations cacheCecil provides a way to cache parts of templates rendering to avoid re-rendering the same partial content multiple times.
\nTo use fragments cache, you must wrap the content you want to cache with the cache tag.
{% cache 'unique-key' %}\n {# cacheable content #}\n{% endcache %}To clear fragments cache only, you can use the following command:
\nphp cecil.phar cache:clear:templates --fragmentsYou can disable cache with the configuration.
\n", "language": "en" }, { "id": "https://cecil-945.pages.dev/documentation/configuration/layouts/", "url": "https://cecil-945.pages.dev/documentation/configuration/layouts/", "title": "Layouts", "summary": "Templates directory, auto-escaping, images, translations and components.", "date_published": "2021-05-07T00:00:00+00:00", "date_modified": "2026-10-05T00:00:00+00:00","content_text": "Layouts\nTemplates options.\nlayouts.dir\nTemplates directory source (layouts by default).\nlayouts:\n dir: layouts\nlayouts.autoescape\nOverrides Twig autoescape option (false by default).\nIf set to null, Cecil uses an extension-based strategy:\n\n*.js.twig -> js\n*.css.twig -> css\n*.html.twig and *.twig -> html\nany other extension -> false\n\nlayouts:\n autoescape: false # disables automatic escaping (default) \n #autoescape: null # use Cecil automatic strategy by template filename extension \n #autoescape: html\n #autoescape: js\nlayouts.images\nImages handling options.\nlayouts:\n images:\n formats: [] # used by `html` function: adds alternatives image formats as `source` (e.g. `[avif, webp]`, empty array by default)\n responsive: false # used by `html` function: adds responsive images ('width' or 'density', `false` by default)\n placeholder: '' # used by `html` function: fills image background before loading (`color` or `lqip`, disabled by default)\n dark_suffix: '' # suffix of the dark variant image (e.g. `.dark`), disabled by default\n mobile_suffix: '' # suffix of the mobile variant image (e.g. `.mobile`), disabled by default\n mobile_media_query: '(max-width: 767px)' # media query of the mobile variant `<source>`\nlayouts.translations\nTranslations handling options.\nlayouts:\n translations:\n dir: translations # translations source directory (`translations` by default)\n formats: # translations supported formats\n yaml:\n loader: Symfony\\Component\\Translation\\Loader\\YamlFileLoader\n ext: [yml, yaml]\n mo:\n loader: Symfony\\Component\\Translation\\Loader\\MoFileLoader\n ext: [mo]\nEach translation format defines:\n\nloader: Symfony translation loader class\next: one or more file extensions associated with this format\n\nlayouts.components\nTemplates Components options.\nlayouts:\n components:\n dir: components # components source directory (`components` by default)\n ext: twig # components files extension (`twig` by default)\nlayouts.sections\nMaps a section to the layouts of another section: the mapped name is used in place of <section> by the lookup rules of the section and of its pages.\nlayouts:\n sections:\n news: blog # the \"news\" section is rendered with `blog\/list.html.twig` and its pages with `blog\/page.html.twig`\nA sub-section already falls back to the layouts of its parent sections: no mapping is needed for that.\n", "content_html": "Templates options.
\nTemplates directory source (layouts by default).
layouts:\n dir: layoutsOverrides Twig autoescape option (false by default).
If set to null, Cecil uses an extension-based strategy:
*.js.twig -> js*.css.twig -> css*.html.twig and *.twig -> htmlfalselayouts:\n autoescape: false # disables automatic escaping (default) \n #autoescape: null # use Cecil automatic strategy by template filename extension \n #autoescape: html\n #autoescape: jsImages handling options.
\nlayouts:\n images:\n formats: [] # used by `html` function: adds alternatives image formats as `source` (e.g. `[avif, webp]`, empty array by default)\n responsive: false # used by `html` function: adds responsive images ('width' or 'density', `false` by default)\n placeholder: '' # used by `html` function: fills image background before loading (`color` or `lqip`, disabled by default)\n dark_suffix: '' # suffix of the dark variant image (e.g. `.dark`), disabled by default\n mobile_suffix: '' # suffix of the mobile variant image (e.g. `.mobile`), disabled by default\n mobile_media_query: '(max-width: 767px)' # media query of the mobile variant `<source>`Translations handling options.
\nlayouts:\n translations:\n dir: translations # translations source directory (`translations` by default)\n formats: # translations supported formats\n yaml:\n loader: Symfony\\Component\\Translation\\Loader\\YamlFileLoader\n ext: [yml, yaml]\n mo:\n loader: Symfony\\Component\\Translation\\Loader\\MoFileLoader\n ext: [mo]Each translation format defines:
\nloader: Symfony translation loader classext: one or more file extensions associated with this formatTemplates Components options.
\nlayouts:\n components:\n dir: components # components source directory (`components` by default)\n ext: twig # components files extension (`twig` by default)Maps a section to the layouts of another section: the mapped name is used in place of <section> by the lookup rules of the section and of its pages.
layouts:\n sections:\n news: blog # the \"news\" section is rendered with `blog/list.html.twig` and its pages with `blog/page.html.twig`Templates can be extended with custom functions and filters, or packaged as a reusable theme.
\nYou can add custom functions and custom filters with a Twig extension.
\nIt’s easy to build a theme, you just have to create a folder <theme> with the following structure (like a website but without pages):
<mywebsite>\n└─ themes\n └─ <theme>\n ├─ config.yml\n ├─ assets\n ├─ layouts\n ├─ static\n └─ translationsDefines where and in what format pages are rendered.
\nDirectory where rendered pages’ files are saved (_site by default).
output:\n dir: _siteList of output formats definition, which are used to render pages (e.g. HTML, Atom, RSS, JSON, XML, etc.).
\noutput:\n formats:\n - name: <name> # name of the format, e.g.: `html` (required)\n mediatype: <media type> # media type (MIME type), ie: 'text/html' (optional)\n subpath: <sub path> # sub path, e.g.: `amp` in `path/amp/index.html` (optional)\n filename: <file name> # file name, e.g.: `index` in `path/index.html` (optional)\n extension: <extension> # file extension, e.g.: `html` in `path/index.html` (required)\n exclude: [<variable>] # don’t apply this format to pages identified by listed variables, e.g.: `[redirect, paginated]` (optional)Those formats are used in the output.pagetypeformats configuration and in the output page variable.
Cecil provides some default formats, which can be overridden in the configuration file: html (default), atom, rss, json, xml, txt, amp, js, webmanifest, xsl, jsonfeed, iframe, oembed.
It’s not required to set output variable for each page, as Cecil automatically applies the formats defined for each page type (homepage, page, section, vocabulary and term).
output:\n pagetypeformats:\n page: [<format>]\n homepage: [<format>]\n section: [<format>]\n vocabulary: [<format>]\n term: [<format>]Several formats can be defined for the one type of page. For example the section page type can be automatically rendered in HTML and Atom:
output:\n pagetypeformats:\n section: [html, atom]output:\n dir: _site\n formats:\n - name: html\n mediatype: text/html\n filename: index\n extension: html\n - name: atom\n mediatype: application/xml\n filename: atom\n extension: xml\n exclude: [redirect, paginated]\n pagetypeformats:\n page: [html]\n homepage: [html, atom]\n section: [html, atom]\n vocabulary: [html]\n term: [html, atom]You can extend Cecil capabilities with an Output post processor to modify the output files after they have been generated.
\nCache options.
\nCache is enabled by default (true), but you can disable it with:
cache:\n enabled: falseDirectory where cache files are stored (.cache by default).
cache:\n dir: '.cache'Assets cache options.
\nTime to live of assets cache in seconds (null by default = no expiration).
cache:\n assets:\n ttl: ~Time to live of remote assets cache in seconds (7 days by default).
\ncache:\n assets:\n remotes:\n ttl: 604800 # 7 daysDisables templates cache with false (true by default).
cache:\n templates: trueDisables translations cache with false (true by default).
cache:\n translations: trueThese options configure the local preview server and the optimization of the generated files.
\nYou can define custom HTTP headers, used by the local preview server.
\n\nserver:\n headers:\n - path: <path> # Relative path, prefixed with a slash. Support \"*\" wildcard.\n headers:\n - key: <key>\n value: \"<value>\"Example:
\nserver:\n headers:\n - path: /*\n headers:\n - key: X-Frame-Options\n value: \"SAMEORIGIN\"\n - key: X-XSS-Protection\n value: \"1; mode=block\"\n - key: X-Content-Type-Options\n value: \"nosniff\"\n - key: Content-Security-Policy\n value: \"default-src 'self'; object-src 'self'; img-src 'self'\"\n - key: Strict-Transport-Security\n value: \"max-age=31536000; includeSubDomains; preload\"\n - path: /assets/*\n headers:\n - key: Cache-Control\n value: \"public, max-age=31536000\"\n - path: /foo.html\n headers:\n - key: Foo\n value: \"bar\"The optimization options allow to enable compression of output files: HTML, CSS, JavaScript and image.
\noptimize:\n enabled: false # enables files optimization (`false` by default)\n html:\n enabled: true # enables HTML files optimization\n ext: [html, htm] # supported files extensions\n css:\n enabled: true # enables CSS files optimization\n ext: [css] # supported files extensions\n js:\n enabled: true # enables JavaScript files optimization\n ext: [js] # supported files extensions\n images:\n enabled: true # enables images files optimization\n ext: [jpeg, jpg, png, gif, webp, svg, avif] # supported files extensionsThis option is disabled by default and can be enabled via:
\noptimize: trueOnce the global option is enabled, the 4 file types will be processed.
\nIt is possible to disable each of them via enabled: false and modify processed files extension via ext.
The configuration can be overridden without editing the configuration file, through environment variables or a CLI option.
\nThe configuration can be overridden through environment variables.
\nAt startup, Cecil also attempts to load a .env file from the current site path (the current working directory, or the <path> argument if provided).
.env file does not exist, Cecil continues normally.Each environment variable name must be prefixed with CECIL_ and the configuration key must be set in uppercase.
For example, the following command set the website’s baseurl:
export CECIL_BASEURL=\"https://example.com/\"You can store the same value in a .env file at your project root:
CECIL_BASEURL=\"https://example.com/\"\nCECIL_TITLE=\"My Cecil site\"You can combine multiple configuration files, with the --config option (left-to-right precedence):
php cecil.phar --config config-1.yml,config-2.ymlCreates a new site.
\nDescription:\n Creates a new website\n\nUsage:\n new:site [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -f, --force Override directory if it already exists\n --demo Add demo content (pages, templates and assets)\n -h, --help Display help for the given command. When no command is given display help for the list command\n -q, --quiet Do not output any message\n -V, --version Display this application version\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nHelp:\n The new:site command creates a new website in the current directory, or in <path> if provided.\n If you run this command without any options, it will ask you for the website title, baseline, base URL, description, etc.\n\n cecil.phar new:site\n cecil.phar new:site path/to/the/working/directory\n\n To create a new website with demo content, run:\n\n cecil.phar new:site --demo\n\n To override an existing website, run:\n\n cecil.phar new:site --forceJamstack platforms can build and deploy your Cecil site automatically on each push to your Git repository.
\n\n\n\nA powerful serverless platform with an intuitive git-based workflow. Automated deployments, shareable previews, and much more.
\n
netlify.toml:
\n[build]\n publish = \"_site\"\n command = \"curl -sSOL https://cecil.app/build.sh && bash ./build.sh\"\n[context.production.environment]\n CECIL_ENV = \"production\"\n[context.deploy-preview.environment]\n CECIL_ENV = \"preview\"\n\n\nVercel combines the best developer experience with an obsessive focus on end-user performance.
\n
vercel.json:
\n{\n \"buildCommand\": \"curl -sSOL https://cecil.app/build.sh && bash ./build.sh\",\n \"outputDirectory\": \"_site\"\n}\n\n\nModern static site hosting with European servers and absolutely no personal data collection!
\n
statichost.yml:
\nimage: wordpress:cli-php8.4\ncommand: curl -sSOL https://cecil.app/build.sh && bash ./build.sh\npublic: _site\n\nCloudflare Pages is a JAMstack platform for frontend developers to collaborate and deploy websites.
\n
➡️ https://pages.cloudflare.com
\nBuild configurations:
\nNonecurl -sSOL https://cecil.app/build.sh && bash ./build.sh_site\n\n\nRender is a unified cloud to build and run all your apps and websites with free TLS certificates, global CDN, private networks and auto deploys from Git.
\n
render.yaml:
\npreviewsEnabled: true\nservices:\n - type: web\n name: Cecil\n env: static\n buildCommand: curl -sSOL https://cecil.app/build.sh && bash ./build.sh\n staticPublishPath: _site\n pullRequestPreviewsEnabled: trueThis guide walks you through creating your first Cecil website, previewing it locally, then building and deploying it.
\nYou can create a new website from scratch in a few minutes.
\nFollow the steps below to create your first Cecil website.
\n\n\nDownload cecil.phar from your terminal:
curl -LO https://cecil.app/cecil.pharYou can also download Cecil manually, or use:
\nbrew install cecilapp/tap/cecilscoop install https://cecil.app/scoop/cecil.jsonCreate a directory for the website (e.g.: <mywebsite>), put cecil.phar in it, then run the new:site command:
php cecil.phar new:siteRun the new:page command:
php cecil.phar new:pageNow you can edit the newly created page with your Markdown editor: <mywebsite>/pages/<new-page>.md.
Run the following command to create a preview of the website:
\nphp cecil.phar serveThen navigate to http://localhost:8000.
When you are satisfied with the result, you can generate the website in order to deploy it on the Web.
\nRun the following command to build the website:
\nphp cecil.phar buildYou can now copy the content of the _site directory to a Web server 🎉
Creates a new page.
\nDescription:\n Creates a new page\n\nUsage:\n new:page [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n --name=NAME Page path name\n --slugify|--no-slugify Slugify file name (or disable --no-slugify)\n -p, --prefix Prefix the file name with the current date (`YYYY-MM-DD`)\n -f, --force Override the file if already exist\n -o, --open Open editor automatically\n --editor=EDITOR Editor to use with open option\n -h, --help Display help for the given command. When no command is given display help for the list command\n -q, --quiet Do not output any message\n -V, --version Display this application version\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nHelp:\n The new:page command creates a new page file.\n If you run this command without any options, it will ask you for the page name and other options.\n\n cecil.phar new:page\n cecil.phar new:page --name=path/to/a-page.md\n cecil.phar new:page --name=path/to/A Page.md --slugify\n\n To create a new page with a date prefix (i.e: `YYYY-MM-DD`), run:\n\n cecil.phar new:page --prefix\n\n To create a new page and open it with an editor, run:\n\n cecil.phar new:page --open --editor=editor\n\n To override an existing page, run:\n\n cecil.phar new:page --forceYou can define your own models for your new pages in the models directory:
blog.md)default.md (for root pages or pages’s section without model)Two dynamic variables are available:
\n%title%: the file’s name%date%: the current dateWith the --open option, the editor will be opened automatically. So use editor key in your configuration file to define the default editor (e.g.: editor: typora).
Continuous integration services can build your site with Cecil and deploy it on each change to your repository.
\n\n\n\nWebsites for you and your projects, hosted directly from your GitHub repository. Just edit, push, and your changes are live.
\n
.github/workflows/build-and-deploy.yml:
\nname: Build and deploy to GitHub Pages\non:\n push:\n branches: [master, main]\n workflow_dispatch:\nconcurrency:\n group: pages\n cancel-in-progress: true\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout source\n uses: actions/checkout@v6\n - name: Restore Cecil cache\n uses: actions/cache/restore@v5\n with:\n path: ./.cache\n key: cecil-cache-\n restore-keys: |\n cecil-cache-\n - name: Build site\n uses: Cecilapp/Cecil-Action@v4\n - name: Save Cecil cache\n uses: actions/cache/save@v5\n with:\n path: ./.cache\n key: cecil-cache-${{ hashFiles('./.cache/**/*') }}\n deploy:\n needs: build\n permissions:\n pages: write\n id-token: write\n environment:\n name: github-pages\n url: ${{ steps.deployment.outputs.page_url }}\n runs-on: ubuntu-latest\n steps:\n - name: Deploy to GitHub Pages\n id: deployment\n uses: actions/deploy-pages@v5\n\nWith GitLab Pages, you can publish static websites directly from a repository in GitLab.
\n
➡️ https://about.gitlab.com/solutions/continuous-integration/
\n.gitlab-ci.yml:
\nimage: wordpress:cli-php8.4\ntest:\n stage: test\n variables:\n CECIL_OUTPUT_DIR: test\n script:\n - curl -sSOL https://cecil.app/build.sh && bash ./build.sh\n artifacts:\n paths:\n - test\n except:\n - master\npages:\n stage: deploy\n variables:\n CECIL_ENV: production\n CECIL_OUTPUT_DIR: public\n script:\n - curl -sSOL https://cecil.app/build.sh && bash ./build.sh\n artifacts:\n paths:\n - public\n only:\n - master\ncache:\n paths:\n - composer-cache/\n - vendor/\n - .cache/Builds and serves the site locally.
\n\nDescription:\n Starts the built-in server\n\nUsage:\n serve [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -o, --open Open web browser automatically\n --host=HOST Server host [default: \"localhost\"]\n --port=PORT Server port [default: \"8000\"]\n -w, --watch|--no-watch Enable (or disable --no-watch) changes watcher (enabled by default)\n -i, --incremental Enable incremental builds (rebuild only changed pages)\n -d, --drafts Include drafts\n --optimize|--no-optimize Enable (or disable --no-optimize) optimization of generated files\n -c, --config=CONFIG Set the path to extra config files (comma-separated)\n --clear-cache[=CLEAR-CACHE] Clear cache before build (optional cache key as regular expression) [default: false]\n -p, --page=PAGE Build a specific page\n --no-ignore-vcs Changes watcher must not ignore VCS directories\n -m, --metrics Show build metrics (duration and memory) of each step\n --timeout=TIMEOUT Sets the process timeout (max. runtime) in seconds [default: 7200]\n --notify Send desktop notification on server start\n -b, --background Run the server in the background\n -h, --help Display help for the given command. When no command is given display help for the list command\n -q, --quiet Do not output any message\n -V, --version Display this application version\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nHelp:\n The serve command starts the live-reloading-built-in web server.\n\n cecil.phar serve\n cecil.phar serve path/to/the/working/directory\n cecil.phar serve --open\n cecil.phar serve --drafts\n cecil.phar serve --no-watch\n\n To speed up local development you can enable incremental builds with the --incremental option.\n When content pages change, Cecil rebuilds just those pages.\n When templates change, Cecil rebuilds only pages using those templates (including Twig dependencies such as extends/include).\n Any other change (data, config, static or asset file, or file deletion) triggers a full rebuild:\n\n cecil.phar serve --incremental\n\n You can use a custom host and port by using the --host and --port options:\n\n cecil.phar serve --host=127.0.0.1 --port=8080\n\n To build the website with an extra configuration file, you can use the --config option.\n This is useful during local development to override some settings without modifying the main configuration:\n\n cecil.phar serve --config=config/dev.yml\n\n To start the server with changes watcher not ignoring VCS directories, run:\n\n cecil.phar serve --no-ignore-vcs\n\n To define the process timeout (in seconds), run:\n\n cecil.phar serve --timeout=7200\n\n To run the server in the background, run:\n\n cecil.phar serve --background\n cecil.phar serve -b\n\n Then stop it with:\n\n cecil.phar serve:stop\n\n In background mode, file changes are not watched automatically.Alias of serve --background: starts the built-in server in the background without occupying the terminal.
Description:\n Starts the built-in server in the background (alias of `serve --background`)\n\nUsage:\n serve:background [options] [--] [<path>]\n\nHelp:\n The serve:background command starts the built-in web server in the background.\n\n cecil.phar serve:background\n cecil.phar serve:background path/to/the/working/directory\n\n This command is an alias of serve --background.\n\n Stop the server with:\n\n cecil.phar serve:stopDisplays the combined server and error logs.
\nDescription:\n Shows combined server and error logs\n\nUsage:\n serve:log [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -l, --lines=LINES Number of entries to display (default: 25)\n\nHelp:\n The serve:log command displays entries from combined server and error logs, sorted by date.\n\n cecil.phar serve:log\n cecil.phar serve:log path/to/the/working/directory\n cecil.phar serve:log --lines=100\n cecil.phar serve:log -l 100\n\n This command shows logs from `.cecil/errors.log` and `.cecil/server.log`.\n It is useful for debugging issues with your local development server.Available locale codes (language_COUNTRY) used by the languages option.
| Locale | \nCode | \n
|---|---|
| Albanian (Albania) | \nsq_AL | \n
| Albanian | \nsq | \n
| Arabic (Algeria) | \nar_DZ | \n
| Arabic (Bahrain) | \nar_BH | \n
| Arabic (Egypt) | \nar_EG | \n
| Arabic (Iraq) | \nar_IQ | \n
| Arabic (Jordan) | \nar_JO | \n
| Arabic (Kuwait) | \nar_KW | \n
| Arabic (Lebanon) | \nar_LB | \n
| Arabic (Libya) | \nar_LY | \n
| Arabic (Morocco) | \nar_MA | \n
| Arabic (Oman) | \nar_OM | \n
| Arabic (Qatar) | \nar_QA | \n
| Arabic (Saudi Arabia) | \nar_SA | \n
| Arabic (Sudan) | \nar_SD | \n
| Arabic (Syria) | \nar_SY | \n
| Arabic (Tunisia) | \nar_TN | \n
| Arabic (United Arab Emirates) | \nar_AE | \n
| Arabic (Yemen) | \nar_YE | \n
| Arabic | \nar | \n
| Belarusian (Belarus) | \nbe_BY | \n
| Belarusian | \nbe | \n
| Bulgarian (Bulgaria) | \nbg_BG | \n
| Bulgarian | \nbg | \n
| Catalan (Spain) | \nca_ES | \n
| Catalan | \nca | \n
| Chinese (China) | \nzh_CN | \n
| Chinese (Hong Kong) | \nzh_HK | \n
| Chinese (Singapore) | \nzh_SG | \n
| Chinese (Taiwan) | \nzh_TW | \n
| Chinese | \nzh | \n
| Croatian (Croatia) | \nhr_HR | \n
| Croatian | \nhr | \n
| Czech (Czech Republic) | \ncs_CZ | \n
| Czech | \ncs | \n
| Danish (Denmark) | \nda_DK | \n
| Danish | \nda | \n
| Dutch (Belgium) | \nnl_BE | \n
| Dutch (Netherlands) | \nnl_NL | \n
| Dutch | \nnl | \n
| English (Australia) | \nen_AU | \n
| English (Canada) | \nen_CA | \n
| English (India) | \nen_IN | \n
| English (Ireland) | \nen_IE | \n
| English (Malta) | \nen_MT | \n
| English (New Zealand) | \nen_NZ | \n
| English (Philippines) | \nen_PH | \n
| English (Singapore) | \nen_SG | \n
| English (South Africa) | \nen_ZA | \n
| English (United Kingdom) | \nen_GB | \n
| English (United States) | \nen_US | \n
| English | \nen | \n
| Estonian (Estonia) | \net_EE | \n
| Estonian | \net | \n
| Finnish (Finland) | \nfi_FI | \n
| Finnish | \nfi | \n
| French (Belgium) | \nfr_BE | \n
| French (Canada) | \nfr_CA | \n
| French (France) | \nfr_FR | \n
| French (Luxembourg) | \nfr_LU | \n
| French (Switzerland) | \nfr_CH | \n
| French | \nfr | \n
| German (Austria) | \nde_AT | \n
| German (Germany) | \nde_DE | \n
| German (Luxembourg) | \nde_LU | \n
| German (Switzerland) | \nde_CH | \n
| German | \nde | \n
| Greek (Cyprus) | \nel_CY | \n
| Greek (Greece) | \nel_GR | \n
| Greek | \nel | \n
| Hebrew (Israel) | \niw_IL | \n
| Hebrew | \niw | \n
| Hindi (India) | \nhi_IN | \n
| Hungarian (Hungary) | \nhu_HU | \n
| Hungarian | \nhu | \n
| Icelandic (Iceland) | \nis_IS | \n
| Icelandic | \nis | \n
| Indonesian (Indonesia) | \nin_ID | \n
| Indonesian | \nin | \n
| Irish (Ireland) | \nga_IE | \n
| Irish | \nga | \n
| Italian (Italy) | \nit_IT | \n
| Italian (Switzerland) | \nit_CH | \n
| Italian | \nit | \n
| Japanese (Japan) | \nja_JP | \n
| Japanese (Japan,JP) | \nja_JP_JP | \n
| Japanese | \nja | \n
| Korean (South Korea) | \nko_KR | \n
| Korean | \nko | \n
| Latvian (Latvia) | \nlv_LV | \n
| Latvian | \nlv | \n
| Lithuanian (Lithuania) | \nlt_LT | \n
| Lithuanian | \nlt | \n
| Macedonian (Macedonia) | \nmk_MK | \n
| Macedonian | \nmk | \n
| Malay (Malaysia) | \nms_MY | \n
| Malay | \nms | \n
| Maltese (Malta) | \nmt_MT | \n
| Maltese | \nmt | \n
| Norwegian (Norway) | \nno_NO | \n
| Norwegian (Norway,Nynorsk) | \nno_NO_NY | \n
| Norwegian | \nno | \n
| Polish (Poland) | \npl_PL | \n
| Polish | \npl | \n
| Portuguese (Brazil) | \npt_BR | \n
| Portuguese (Portugal) | \npt_PT | \n
| Portuguese | \npt | \n
| Romanian (Romania) | \nro_RO | \n
| Romanian | \nro | \n
| Russian (Russia) | \nru_RU | \n
| Russian | \nru | \n
| Serbian (Bosnia and Herzegovina) | \nsr_BA | \n
| Serbian (Montenegro) | \nsr_ME | \n
| Serbian (Serbia and Montenegro) | \nsr_CS | \n
| Serbian (Serbia) | \nsr_RS | \n
| Serbian | \nsr | \n
| Slovak (Slovakia) | \nsk_SK | \n
| Slovak | \nsk | \n
| Slovenian (Slovenia) | \nsl_SI | \n
| Slovenian | \nsl | \n
| Spanish (Argentina) | \nes_AR | \n
| Spanish (Bolivia) | \nes_BO | \n
| Spanish (Chile) | \nes_CL | \n
| Spanish (Colombia) | \nes_CO | \n
| Spanish (Costa Rica) | \nes_CR | \n
| Spanish (Dominican Republic) | \nes_DO | \n
| Spanish (Ecuador) | \nes_EC | \n
| Spanish (El Salvador) | \nes_SV | \n
| Spanish (Guatemala) | \nes_GT | \n
| Spanish (Honduras) | \nes_HN | \n
| Spanish (Mexico) | \nes_MX | \n
| Spanish (Nicaragua) | \nes_NI | \n
| Spanish (Panama) | \nes_PA | \n
| Spanish (Paraguay) | \nes_PY | \n
| Spanish (Peru) | \nes_PE | \n
| Spanish (Puerto Rico) | \nes_PR | \n
| Spanish (Spain) | \nes_ES | \n
| Spanish (United States) | \nes_US | \n
| Spanish (Uruguay) | \nes_UY | \n
| Spanish (Venezuela) | \nes_VE | \n
| Spanish | \nes | \n
| Swedish (Sweden) | \nsv_SE | \n
| Swedish | \nsv | \n
| Thai (Thailand) | \nth_TH | \n
| Thai (Thailand,TH) | \nth_TH_TH | \n
| Thai | \nth | \n
| Turkish (Turkey) | \ntr_TR | \n
| Turkish | \ntr | \n
| Ukrainian (Ukraine) | \nuk_UA | \n
| Ukrainian | \nuk | \n
| Vietnamese (Vietnam) | \nvi_VN | \n
| Vietnamese | \nvi | \n
The built site can be uploaded as is to any static hosting service.
\n\n\n\nShipping web projects should be fast, easy, and low risk. Surge is static web publishing for Front-End Developers, right from the CLI.
\n
Terminal:
\nnpm install -g surge\nsurge _site/Builds the site.
\nDescription:\n Builds the website\n\nUsage:\n build [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -d, --drafts Include drafts\n -u, --baseurl=BASEURL Set the base URL\n -o, --output=OUTPUT Set the output directory\n --optimize|--no-optimize Enable (or disable --no-optimize) optimization of generated files\n --dry-run Build without saving\n -c, --config=CONFIG Set the path to extra config files (comma-separated)\n --clear-cache[=CLEAR-CACHE] Clear cache before build (optional cache key as regular expression) [default: false]\n -p, --page=PAGE Build a specific page\n --render-subset=RENDER-SUBSET Render a subset of pages\n --show-pages Show list of built pages in a table\n -m, --metrics Show build metrics (duration and memory) of each step\n --notify Send desktop notification on build completion\n -h, --help Display help for the given command. When no command is given display help for the list command\n -q, --quiet Do not output any message\n -V, --version Display this application version\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nHelp:\n The build command generates the website in the output directory.\n\n cecil.phar build\n cecil.phar build path/to/the/working/directory\n cecil.phar build --baseurl=https://example.com/\n cecil.phar build --output=_site\n\n To build the website with optimization of generated files, you can use the --optimize option.\n This is useful to reduce the size of the generated files and improve performance:\n\n cecil.phar build --optimize\n cecil.phar build --no-optimize\n\n To build the website without overwriting files in the output directory, you can use the --dry-run option.\n This is useful to check what would be built without actually writing files:\n\n cecil.phar build --dry-run\n\n To build the website with a specific subset of rendered pages, you can use the --render-subset option.\n This is useful to build only a part of the website, for example, only \"hot\" pages or a specific section:\n\n cecil.phar build --render-subset=subset\n\n To show build steps metrics, run:\n\n cecil.phar build --metricsTo get started quickly, use one of Cecil's ready-to-use starter kits.
\nDiagnoses the current site and Cecil environment.
\n![\"Starter](\"/docs/cecil-newblog.c85c682e3bcb416589e2bc2bbcc2cfca.png\")
\nDescription:\n Diagnoses the site configuration\n\nUsage:\n doctor [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -c, --config=CONFIG Set the path to an extra configuration file\n -h, --help Display help for the given command. When no command is given display help for the list command\n -q, --quiet Do not output any message\n -V, --version Display this application version\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nHelp:\n The doctor command diagnoses the current site and Cecil environment.\n\n cecil.phar doctor\n cecil.phar doctor path/to/the/working/directory\n\n To inspect a site with an extra configuration file, run:\n\n cecil.phar doctor --config=config.ymlValidates pages front matter syntax.
\nDescription:\n Validates pages front matter syntax\n\nUsage:\n doctor:frontmatter|doctor:fm [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -c, --config=CONFIG Set the path to an extra configuration file\n -p, --page=PAGE Validate a single page relative to the pages directory\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -h, --help Display help for the given command. When no command is given display help for the list command\n -q, --quiet Do not output any message\n -V, --version Display this application version\n -v|vv|vvv Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debugAudits rendered HTML pages for common SEO issues.
\nDescription:\n Audits rendered HTML pages for common SEO issues\n\nUsage:\n doctor:seo [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -c, --config=CONFIG Set the path to an extra configuration file\n -p, --page=PAGE Audit a single page relative to the pages directory\n --format=FORMAT Output format: text (default) or json\n --feedback Include findings with feedback level\n --include-virtual Include virtual pages (paginated, taxonomies) in audit\n --fail-on=FAIL-ON Return a failure exit code when findings of this level or higher are found: bad (default), ok, feedback or neverThe command builds the site in dry-run mode, then audits the rendered HTML output for a focused set of checks: title tag, meta description, canonical URL, heading structure, Open Graph tags, image alt attributes and estimated content length.
\nBy default, virtual pages (paginated, taxonomy pages) are excluded from the audit. Use --include-virtual to include them.
By default, findings with level feedback are not listed.
Use --feedback to include findings with level feedback in addition to other findings.
Output results as JSON for CI integration using --format=json.
By default, the command returns a failure exit code (1) when findings with level bad are found. Use --fail-on=ok to also fail on ok findings, --fail-on=feedback to fail on any finding, or --fail-on=never to always succeed.
Customize audit thresholds and enabled checks in your configuration file:
\ndoctor:\n seo:\n title: { min: 30, max: 60 }\n description: { min: 120, max: 160 }\n content: { min_words: 300 }\n checks:\n title: true\n description: true\n canonical: true\n h1: true\n og_tags: true\n img_alt: true\n content_length: true\n lang_attribute: trueChecks internal and external links of the rendered pages.
\nDescription:\n Checks internal and external links of the rendered pages\n\nUsage:\n doctor:links [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -c, --config=CONFIG Set the path to an extra configuration file\n -p, --page=PAGE Check links of a single page relative to the pages directory\n --internal Check internal links\n --external Check external links\n --exclude=EXCLUDE Exclude links matching this regular expression (multiple values allowed)\n --timeout=TIMEOUT External links request timeout, in seconds\n --concurrency=CONCURRENCY Number of concurrent external links requests\n --no-cache Do not use cached external links results\n --format=FORMAT Output format: text (default) or json\n --include-virtual Include virtual pages (paginated, taxonomies) in audit\n --feedback Include findings with feedback level\n --fail-on=FAIL-ON Return a failure exit code when findings of this level or higher are found: bad (default), ok, feedback or neverThe command builds the site in dry-run mode, then checks the links found in the rendered HTML pages: links (<a>, <area>, <link>), images (src and srcset), scripts, iframes, media and inline styles. CSS files linked from the pages are also analyzed (url() and @import).
#anchor) must match an element ID of the target page. Absolute URLs starting with baseurl are considered as internal links.HEAD, then GET if the server refuses HEAD), concurrently. Successful results are cached (24 hours by default): use --no-cache to check them again.By default, only internal links are checked:
\nphp cecil.phar doctor:links # internal links (default)\nphp cecil.phar doctor:links --external # external links only\nphp cecil.phar doctor:links --internal --external # bothFindings levels:
\n| Level | \nMeaning | \n
|---|---|
bad | \nBroken link: target not found, missing anchor, HTTP error (4xx, 5xx), unresolved host, etc. | \n
ok | \nWorking link that could be improved: redirection, missing trailing slash | \n
feedback | \nUnverifiable link: access denied (401, 403, 429), probably by a bot protection, or timeout | \n
Links using other schemes than HTTP (e.g.: mailto:, tel:, data:) are ignored. Use --exclude (regular expression, case insensitive) to ignore other links.
--page, --include-virtual, --feedback, --format and --fail-on options behave as with doctor:seo (see above).
Customize default settings in your configuration file:
\ndoctor:\n links:\n internal: true # check internal links\n external: false # check external links\n timeout: 10 # external links request timeout, in seconds\n concurrency: 10 # number of concurrent external links requests\n cache_ttl: 86400 # external links successful results cache TTL, in seconds\n exclude: [] # links to ignore (list of regular expressions), e.g.: ['linkedin\\.com', '^https://localhost']\n useragent: ~ # User-Agent header of external links requests (`assets.remote.useragent.default` by default)