Cecil is distributed as a single executable file, cecil.phar, which runs anywhere PHP is installed.

Requirements

• PHP 8.3+
• PHP extensions: fileinfo, gd and mbstring

Check your PHP version and loaded extensions:

php -v
php -m

Optional extensions

Download the PHAR

Download cecil.phar from your terminal:

curl -LO https://cecil.app/cecil.phar

Then run it with PHP:

php cecil.phar --version

Install globally

Installing Cecil globally allows you to run the cecil command from any directory, instead of php cecil.phar.

macOS and Linux

With Homebrew:

brew install cecilapp/tap/cecil

Or manually, by moving the PHAR in a directory of your PATH:

mv cecil.phar /usr/local/bin/cecil
chmod +x /usr/local/bin/cecil

Windows

With Scoop:

scoop install https://cecil.app/scoop/cecil.json

Or manually:

1. Move cecil.phar in a dedicated directory, like C:\bin
2. Rename it from cecil.phar to cecil
3. Append ;C:\bin to your PATH environment variable
4. Create a wrapping batch script next to it

PHIVE

With PHIVE (The PHAR Installation and Verification Environment):

phive install cecil

Composer

With Composer:

composer global require cecil/cecil

Verify the installation

cecil --version

Update

Update Cecil to the latest version according to your installation method:

# PHAR
php cecil.phar self-update
# Homebrew
brew upgrade cecilapp/tap/cecil
# Scoop
scoop update cecil
# PHIVE
phive update cecil
# Composer
composer global update cecil/cecil

The 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 version

Troubleshooting

command not found: cecil

The installation directory is not in your PATH: add it, or run Cecil with php cecil.phar from the directory containing the PHAR.

PHP version or extension error

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.

Diagnose a website

Once a website is created, run the doctor command to diagnose its configuration.

Diagram

graph TD
    %% Entry
    CLI["bin/cecil\n(CLI entry point)"]
    APP["Application\n(Symfony Console)"]
    CMD["Commands\nbuild / serve / new:site\nnew:page / clear / show:content"]

    CLI --> APP --> CMD

    %% Orchestrator
    BUILDER["Builder\n(Orchestrator)"]
    CONFIG["Configuration\n(config.yml + default.php\n+ themes)"]
    CMD --> BUILDER
    CONFIG --> BUILDER

    %% Pipeline
    subgraph PIPELINE["Build pipeline (steps)"]
        S1["1. Pages/Load\n(Finder -> Markdown files)"]
        S2["2. Data/Load\n(YAML files)"]
        S3["3. StaticFiles/Load\n(load static files)"]
        S4["4. Pages/Create\n(create Page objects)"]
        S5["5. Pages/Convert\n(Markdown -> HTML\nfront matter)"]
        S6["6. Taxonomies/Create\n(create taxonomies)"]
        S7["7. Pages/Generate\n(generators)"]
        S8["8. Menus/Create\n(create menus)"]
        S9["9. StaticFiles/Copy\n(copy static files)"]
        S10["10. Pages/Render\n(Twig rendering)"]
        S11["11. Pages/Save\n(save pages)"]
        S12["12. Assets/Save\n(save assets)"]
        S13["13. Optimize/*\n(optimize HTML/CSS/JS/Images)"]

        S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10 --> S11 --> S12 --> S13
    end

    BUILDER --> PIPELINE

    %% Subsystems
    subgraph COLLECTIONS["Collections"]
        PC["PagesCollection\n(Page objects)"]
        TC["TaxonomiesCollection\n(vocabularies/terms)"]
        MC["MenusCollection"]
    end

    subgraph GENERATORS["Generators (virtual pages)"]
        GP["Pagination"]
        GT["Taxonomy"]
        GS["Section"]
        GR["Redirect"]
        GD["DefaultPages (home, 404)"]
    end

    subgraph RENDERER["Twig rendering"]
        TW["Twig engine"]
        EXT["Extensions\n(Core, Content, Collection)"]
        PP["PostProcessors\n(metadata, excerpts, links)"]
        TH["Themes / Layouts"]
        TW --> EXT
        TW --> PP
        TH --> TW
    end

    subgraph ASSETS["Assets"]
        AL["Asset locator"]
        AC["Compiler\n(SCSS -> CSS)"]
        AI["Image processor\n(responsive, WebP, AVIF)"]
        AO["Optimizer\n(CSS/JS minification)"]
    end

    subgraph OUTPUT["Output (_site/)"]
        HTML[".html pages"]
        CSS2["CSS/JS assets"]
        IMG["images"]
        SF["static files"]
    end

    S4 --> PC
    S6 --> TC
    S8 --> MC
    S7 --> GENERATORS
    GENERATORS --> PC
    S10 --> RENDERER
    S12 --> ASSETS

    PC --> RENDERER
    TC --> RENDERER
    MC --> RENDERER

    RENDERER --> S11
    S11 --> HTML
    S12 --> CSS2
    S12 --> IMG
    S9 --> SF

    %% Inputs
    subgraph INPUT["Sources"]
        MD["content/\n(Markdown + front matter)"]
        DATA["data/\n(YAML)"]
        STATIC["static/"]
        LAYOUTS["layouts/\n(Twig templates)"]
    end

    MD --> S1
    DATA --> S2
    STATIC --> S3
    LAYOUTS --> TH

Key Components Legend

Cecil provides a simple PHP API to build your website.

You can read the API documentation for more details.

Installation

composer require cecil/cecil

libvips support

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

composer require intervention/image-driver-vips

Usage

Build

Build a new website with a custom configuration:

require_once 'vendor/autoload.php';

use Cecil\Builder;

$config = [
    'title'   => "My website",
    'baseurl' => 'https://domain.tld/',
];

Builder::create($config)->build();

exec('php -S localhost:8000 -t _site'); // preview locally

Diagnostic

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

<?php

require_once 'vendor/autoload.php';

use Cecil\Builder;
use Cecil\Doctor\SeoDoctor;
use Cecil\Doctor\SiteDoctor;

$builder = Builder::create(require 'config.php')
    ->setSourceDir(__DIR__)
    ->setDestinationDir(__DIR__);

$siteDoctor = new SiteDoctor();
$diagnosis = $siteDoctor->diagnose($builder, __DIR__, ['cecil.yml']);

$seoDoctor = new SeoDoctor();
$seoAudit = $seoDoctor->audit($builder, [
    'page' => '',
    'include_virtual' => false,
]);

var_dump($diagnosis['errors'], $seoAudit['summary']);

Examples of CDN providers configuration.

Cloudinary

https://cloudinary.com

assets:
  images:
    cdn:
      enabled: true
      account: 'xxxx'
      url: 'https://res.cloudinary.com/%account%/image/fetch/c_limit,w_%width%,q_%quality%,f_%format%,d_default/%image_url%'

Cloudimage

https://www.cloudimage.io

assets:
  images:
    cdn:
      enabled: true
      account: 'xxxx'
      url: 'https://%account%.cloudimg.io/%image_url%?w=%width%&q=%quality%&force_format=%format%'

TwicPics

https://www.twicpics.com

assets:
  images:
    cdn:
      enabled: true
      account: 'xxxx'
      canonical: false
      remote: false
      url: 'https://%account%.twic.pics/%image_url%?twic=v1/resize=%width%/quality=%quality%/output=%format%'

Source URL: Your website baseurl.

imgix

https://imgix.com

assets:
  images:
    cdn:
      enabled: true
      account: 'xxxx'
      canonical: false
      remote: false
      url: 'https://%account%.imgix.net/%image_url%?w=%width%&q=%quality%&fm=%format%'

Base URL: Your website baseurl.

Netlify Image CDN

https://docs.netlify.com/image-cdn/overview/

assets:
  images:
    cdn:
      enabled: true
      canonical: false
      url: '/.netlify/images?url=%image_url%&w=%width%&fm=%format%'

Run locally

Setup Netlify CLI

npm install netlify-cli -g
netlify link

netlify.toml:

[dev]
  targetPort = 8000

Run local server

php cecil.phar serve & netlify dev

Open http://localhost:8888

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

Pages Generator

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

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

Example:

/extensions/Cecil/Generator/DummyPage.php

<?php
namespace Cecil\Generator;

use Cecil\Collection\Page\Page;
use Cecil\Collection\Page\Type;

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

/extensions/Cecil/Generator/Database.php

<?php
namespace Cecil\Generator;

use Cecil\Collection\Page\Page;
use Cecil\Collection\Page\Type;

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

configuration

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

Twig extension

You can add custom functions and filters:

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

Example:

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

<?php
namespace Cecil\Renderer\Extension;

class MyTwigExtension extends \Twig\Extension\AbstractExtension
{
    public function getFilters()
    {
        // add a new filter named 'md5'
        return [
            new \Twig\TwigFilter('md5', 'md5'),
        ];
    }
}

configuration

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

Output Post Processor

You can post process page output.

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

Example:

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

<?php
namespace Cecil\Renderer\PostProcessor;

use Cecil\Collection\Page\Page;

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

        return $output;
    }
}

configuration

output:
  postprocessors:
    MyProcessor: Cecil\Renderer\PostProcessor\MyProcessor

image_srcset

Builds the HTML img srcset (responsive) attribute of an image Asset.

{{ image_srcset(asset) }}

Examples:

{% set asset = asset(image_path) %}
<img src="{{ url(asset) }}" width="{{ asset.width }}" height="{{ asset.height }}" alt="" class="asset" srcset="{{ image_srcset(asset) }}" sizes="{{ image_sizes('asset') }}">

image_sizes

Returns the HTML img sizes attribute based on a CSS class name.
It should be use in conjunction with the image_srcset function.

{{ image_sizes('class') }}

Examples:

{% set asset = asset(image_path) %}
<img src="{{ url(asset) }}" width="{{ asset.width }}" height="{{ asset.height }}" alt="" class="asset" srcset="{{ image_srcset(asset) }}" sizes="{{ image_sizes('asset') }}">

image_from_website

Builds the HTML img element from a website URL by extracting its illustration image. Returns 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:

1. Open Graph: og:image:secure_url, og:image, og:image:url
2. Twitter: twitter:image, twitter:image:src
3. <link rel="image_src">
4. Microdata: itemprop="image"
5. JSON-LD: image property
6. First <img> of <article>, <main> or <body>
7. <link rel="apple-touch-icon">
8. <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:

• fallback: image path (or URL) used if no image is found
• other image options (e.g.: responsive, formats)

Examples:

{{ image_from_website('https://example.com/page-with-image.html') }}

{# with a fallback image #}
{{ image_from_website('https://example.com/', {alt: 'Illustration'}, {fallback: 'images/default.png'}) }}

resize

Resizes an image to a specified width (in pixels) or/and height (in pixels).

• If only the width is specified, the height is calculated to preserve the aspect ratio
• If only the height is specified, the width is calculated to preserve the aspect ratio
• If both width and height are specified, the image is resized to fit within the given dimensions, image is cropped and centered if necessary
• If remove_animation is true, any animation in the image (e.g., GIF) will be removed

{{ asset(image_path)|resize(width: width, height: height, remove_animation: bool) }}

Examples:

{{ asset(page.image)|resize(300) }}
{# equivalent to: #}
{{ asset(page.image)|resize(width: 300) }}
{# resizes to 300px width, height auto-calculated to preserve aspect ratio #}
{{ asset(page.image)|resize(height: 200) }}
{# resizes to 300px width and 200px height, and crops if necessary #}
{{ asset(page.image)|resize(300, 200) }}
{# removes any animation from the image #}
{{ asset(page.image)|resize(width: 1200, height: 630, remove_animation: true) }}

cover

Resizes an image to a specified width and height, cropping it if necessary.

{{ asset(image_path)|cover(width, height) }}

Example:

{{ asset(page.image)|cover(1200, 630) }}

maskable

Adds padding, in pourcentages, to an image to make it maskable.

{{ asset(image_path)|maskable(padding) }}

Example:

{{ asset('icon.png')|maskable }}

webp

Converts an image to WebP format.

Example:

<picture>
    <source type="image/webp" srcset="{{ asset(image_path)|webp }}">
    <img src="{{ url(asset(image_path)) }}" width="{{ asset(image_path).width }}" height="{{ asset(image_path).height }}" alt="">
</picture>

avif

Converts an image to AVIF format.

Example:

<picture>
    <source type="image/avif" srcset="{{ asset(image_path)|avif }}">
    <img src="{{ url(asset(image_path)) }}" width="{{ asset(image_path).width }}" height="{{ asset(image_path).height }}" alt="">
</picture>

lqip

Returns a Low Quality Image Placeholder (100x100 px, 50% blurred) as data URL.

{{ asset(image_path)|lqip }}

dominant_color

Returns the dominant hexadecimal color of an image.

{{ asset(image_path)|dominant_color }}

title

Main title of the site.

title: "<site title>"

baseline

Short description (~ 20 characters).

baseline: "<baseline>"

baseurl

The base URL.

baseurl: <url>

Example:

baseurl: http://localhost:8000/

canonicalurl

If set to true the url() function will return the absolute URL (false by default).

canonicalurl: <true|false> # false by default

description

Site description (~ 250 characters).

description: "<description>"

menus

Menus are used to create navigation links in templates.

A menu is made up of a unique ID and entry properties (name, URL, weight).

menus:
  <name>:
    - id: <unique-id>   # unique identifier (required)
      name: "<name>"    # name displayed in templates
      url: <url>        # relative or absolute URL
      weight: <integer> # integer value used to sort entries (lighter first)

Example:

menus:
  main:
    - id: about
      name: "About"
      url: /about/
      weight: 1
  footer:
    - id: author
      name: The author
      url: https://arnaudligny.fr
      weight: 99

Override an entry

A page menu entry can be overridden: use the page ID as id.

Example:

menus:
  main:
    - id: index
      name: "My amazing homepage!"
      weight: 1

Disable an entry

A menu entry can be disabled with enabled: false.

Example:

menus:
  main:
    - id: about
      enabled: false

taxonomies

List of vocabularies, paired by plural and singular value.

taxonomies:
  <plural>: <singular>

Example:

taxonomies:
  categories: category
  tags: tag

Then you can use those vocabularies in your content’s front matter.

theme

The theme to use, or a list of themes.

theme: <theme> # theme name
# or
theme:
  - <theme1> # theme name
  - <theme2>

Examples:

theme: hyde

theme:
  - serviceworker
  - hyde

date

Date format and timezone.

date:
  format: <format>     # date format (optional, `F j, Y` by default)
  timezone: <timezone> # date timezone (optional, local time zone by default)

• format: PHP date format specifier
• timezone: see timezones

Example:

date:
  format: 'j F, Y'
  timezone: 'Europe/Paris'

metatags

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:

• Page title + Site title, or Site title + Site baseline
• Page/Site description
• Page/Site keywords
• Page/Site author
• Search engine crawler directives (robots)
• Favicon links
• Navigation links (first, previous, next, last)
• Canonical URL
• Alternate links (i.e.: RSS feed, others languages)
• rel=me links
• Open Graph
• Facebook profile ID
• Twitter/X Card
• Fediverse tag
• Dublin Core
• Structured data (JSON-LD)

metatags options

Cecil uses page front matter to feed meta tags, and falls back to site options when needed.

title: "Page/Site title"              # used by title meta
description: "Page/Site description"  # used by description meta
tags: [tag1, tag2]                    # used by keywords meta
keywords: [keyword1, keyword2]        # obsolete
author:                               # used by author meta
  name: <name>                          # author name
  url: <url>                            # author URL
  email: <email>                        # author email
image: image.jpg                      # used by Open Graph and social networks cards
canonical:                            # used to override the generated canonical URL
  url: <URL>                            # absolute URL
  title: "<URL title>"                  # optional canonical title
social:                               # used by social networks meta
  twitter:                              # used by Twitter/X Card
    url: <URL>                            # used for `rel=me` link
    site: username                        # site username
    creator: username                     # page author username
  mastodon:                             # used by Mastodon meta
    url: <URL>                            # used for `rel=me` link
    creator: handle                       # page author account
  facebook:                             # used by Facebook meta
    url: <URL>                            # used for `rel=me` link
    id: 123456789                         # Facebook profile ID
    username: username                    # page author username

metatags configuration

metatags:
  title:                   # title options
    divider: " · "    # string between page title and site title
    only: false              # displays page title only (`false` by default)
    pagination:              # pagination options
      shownumber: true         # displays page number in title (`true` by default)
      label: "Page %s"         # how to display page number (`Page %s` by default)
  robots: "index,follow"   # web crawlers directives (`index,follow` by default)
  favicon:                 # favicon options
    enabled: true            # includes favicon (`true` by default)
    image: favicon.png       # path to favicon image
    sizes:                   # sizes by device
      - "icon": [32, 57, 76, 96, 128, 192, 228]  # web browsers
      - "shortcut icon": [196]                   # Android
      - "apple-touch-icon": [120, 152, 180]      # iOS
  navigation: true         # includes previous and next links (`true` by default)
  image: true              # includes image (`true` by default)
  og: true                 # includes Open Graph meta tags (`true` by default)
  articles: "blog"         # articles' section (`blog` by default)
  twitter: true            # includes Twitter/X Card meta tags (`true` by default)
  mastodon: true           # includes Mastodon meta tags (`true` by default)
  dc: false                # includes Dublin Core meta tags (`false` by default)
  data: false              # includes JSON-LD structured data (`false` by default)

debug

Enables the debug mode, used to display debug information like very verbose logs, Twig dump, Twig profiler, SCSS sourcemap, etc.

debug: true

There are two other ways to enable debug mode:

1. Run a command with the -vvv option
2. Set the CECIL_DEBUG environment variable to true

A page is a file made up of a front matter and a body.

Front matter

The front matter is a collection of variables (in key/value format) surrounded by ---.

Example:

---
title: "The title"
date: 2019-02-21
tags: [tag 1, tag 2]
customvar: "Value of customvar"
---

Body

Body is the main content of a page, it could be written in Markdown or in plain text.

Example:

# Header

[toc]

## Sub-Header 1

Lorem ipsum dolor [sit amet](https://example.com), consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<!-- excerpt -->
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Sub-Header 2

![Description](/image.jpg "Title")

## Sub-Header 3

:::tip
This is advice.
:::

File prefix

The filename can contain a prefix to define date or weight variables of the page (used by sortby).

date

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:

In « 2019-04-23_My blog post.md »:

• the prefix is « 2019-04-23 »
• the date of the page is « 2019-04-23 »
• the title of the page is « My blog post »

weight

The weight prefix is used to set the sort order of the page, and must be a valid integer value.

Example:

In « 1_The first project.md »:

• the prefix is « 1 »
• the weight of the page is « 1 »
• the title of the page is « The first project »

Section

Some dedicated variables can be used in a custom Section (i.e.: <section>/index.md).

sortby

The order of pages in a Section can be changed.

Available values are:

• date: more recent first
• title: alphabetic order
• weight: lightest first

Example:

---
sortby: title
---

More options:

---
sortby:
  variable: date    # "date", "updated", "title" or "weight"
  desc_title: false # used with "date" or "updated" variable value to sort by desc title order if items have the same date
  reverse: false    # reversed if true
---

pagination

The global pagination configuration is used by default, but you can change it for a specific Section.

Example:

---
pagination:
  max: 5
  path: "page"
---

Pagination can be disabled for a Section:

---
pagination: false
---

cascade

Any variables in cascade are added to the front matter of all sub pages.

Example:

---
cascade:
  banner: image.jpg
---

circular

Set circular to true to enable circular navigation with page.<prev/next>.

Example:

---
circular: true
---

Sub-section

A nested folder that explicitly contains an index.md file is turned into a sub-section of its parent Section.

<mywebsite>
└─ pages
   └─ blog                 <- Section
      ├─ index.md
      ├─ post-1.md         <- Page in Section "blog"
      └─ 2024              <- Sub-section (contains an "index.md")
         ├─ index.md
         └─ post-2.md      <- Page in Section "blog" *and* sub-section "blog/2024"

A sub-section:

• is a Section (same type, variables and layout resolution) available at its own URL (e.g.: /blog/2024/)
• is rendered with the layouts of its parent Sections if it doesn't have its own (e.g.: blog/list.html.twig)
• can be nested at any depth (e.g.: blog/2024/06/)
• lists its own pages, and its pages also belong to each of their parent Sections
• is not listed in its parent Section
• is placed in the page.<prev/next> navigation of its parent Section (according to its sortby), followed by its own pages

Home page

Like another section, Home page support sortby and pagination configuration.

pagesfrom

Set a valid Section name in pagesfrom to use pages collection from this Section in Home page.

Example:

---
pagesfrom: blog
---

Files organization

Kinds of templates

There are three kinds of templates: layouts, components, and other templates. Layouts are used to render pages, and each layout can include templates and components.

Naming convention

Template 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)

The section of the page (e.g.: blog).

<type>

The page type: home (or index) for homepage, list for list, page for page, etc. (See Lookup rules for details).

<layout> (optional)

The custom layout name defined in the front matter of the page (e.g.: layout: my-layout).

<format>

The output format of the rendered page (e.g.: html, rss, json, xml, etc.).

<language> (optional)

The language of the page (e.g.: fr).

Examples:

layouts/home.html.twig       # `type` is "homepage"
layouts/page.html.twig       # `type` is "page"
layouts/page.html.fr.twig    # `type` is "page" and `language` is "fr"
layouts/my-layout.html.twig  # `layout` is "my-layout"
layouts/blog/list.html.twig  # `section` is "blog"
layouts/blog/list.rss.twig   # `section` is "blog" and `format` is "rss"

<my-site>
├─ ...
├─ layouts
|  ├─ index.html.twig      # Used by type "homepage"
|  ├─ list.html.twig       # Used by types "homepage" and "section"
|  ├─ list.rss.twig        # Used by types "homepage" and "section", for RSS output format
|  ├─ page.html.twig       # Used by type "page"
|  ├─ taxonomy
|  |  ├─ tags.html.twig    # Used by type "vocabulary" of `tags` (list of terms)
|  |  └─ tag.html.twig     # Used by type "term" of `tags` (list of pages)
|  ├─ my-layout.html.twig  # Used by pages with `layout: my-layout` in the front matter
|  ├─ ...
|  └─ partials             # Included templates
|     ├─ footer.html.twig
|     └─ ...
└─ themes                  # Themes layouts and templates
   └─ ...

Built-in templates

Cecil comes with a set of built-in templates.

Lookup rules

In most of cases you don’t need to specify the layout: Cecil selects the most appropriate layout, according to the page type.

For example, the HTML output of home page (index.md) will be rendered:

1. with my-layout.html.twig if the layout variable is set to "my-layout" (in the front matter)
2. if not, with index.html.twig if the file exists
3. if not, with home.html.twig if the file exists
4. if not, with list.html.twig if the file exists

All rules are detailed below, for each page type, in the priority order.

Type homepage

1. <layout>.<format>.twig
2. index.<format>.twig
3. home.<format>.twig
4. list.<format>.twig
5. _default/<layout>.<format>.twig
6. _default/index.<format>.twig
7. _default/home.<format>.twig
8. _default/list.<format>.twig
9. _default/page.<format>.twig

Type page

1. <section>/<layout>.<format>.twig
2. <layout>.<format>.twig
3. <section>/page.<format>.twig
4. _default/<layout>.<format>.twig
5. page.<format>.twig
6. _default/page.<format>.twig

Type section

1. <layout>.<format>.twig
2. <section>/index.<format>.twig
3. <section>/list.<format>.twig
4. section/<section>.<format>.twig
5. <parent>/index.<format>.twig, <parent>/list.<format>.twig and section/<parent>.<format>.twig, for each parent section of a sub-section (nearest first)
6. _default/section.<format>.twig
7. list.<format>.twig
8. _default/list.<format>.twig

Type vocabulary

1. taxonomy/<plural>.<format>.twig
2. vocabulary.<format>.twig
3. _default/vocabulary.<format>.twig

Type term

1. taxonomy/<plural>/<term>.<format>.twig
2. taxonomy/<singular>.<format>.twig
3. term.<format>.twig
4. _default/term.<format>.twig
5. _default/list.<format>.twig

Functions can be called to generate content. Functions are called by their name followed by parentheses (()) and may have arguments.

url

Creates a valid URL for a page, a menu entry, an asset, a page ID or a path.

{{ url(value, {options}) }}

Examples:

{# page #}
{{ url(page) }}
{{ url(page, {canonical: true}) }}
{{ url(page, {format: json}) }}
{{ url(page, {language: fr}) }}
{# menu entry #}
{{ url(site.menus.main.about) }}
{# asset #}
{{ url(asset('styles.css')) }}
{# page ID #}
{{ url('page-id') }}
{# path #}
{{ url('about-me/') }}
{{ url('tags/' ~ tag) }}

html

Creates an HTML element from an asset (or an array of assets with custom attributes).

{{ html(asset, {attributes}, {options}) }}
{# dedicated functions for each common type of asset #}
{{ css(asset) }}
{{ js(asset) }}
{{ image(asset) }}
{{ audio(asset) }}
{{ video(asset) }}

Examples:

{# CSS with an attribute #}
{{ html(asset('print.css'), {media: 'print'}) }}
{# CSS with an attribute and an option #}
{{ html(asset('styles.css'), {title: 'Main theme'}, {preload: true}) }}
{# Array of assets with media query #}
{{ html([
  {asset: asset('css/style.css')},
  {asset: asset('css/style-dark.css'), attributes: {media: '(prefers-color-scheme: dark)'}}
]) }}
{# JavaScript #}
{{ html(asset('script.js')) }}
{# image without specific attributes nor options #}
{{ html(asset('image.png')) }}
{# image with specific attributes, responsive images and alternative formats #}
{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {responsive: true, formats: ['avif', 'webp']}) }}
{# image with responsive pixels density images #}
{{ html(asset('image.jpg'), options={responsive: 'density'}, attributes={width: 256}) }}
{# image with a Low-Quality Image Placeholder #}
{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {placeholder: 'lqip'}) }}
{# Audio #}
{{ html(asset('audio.mp3')) }}
{# Video #}
{{ html(asset('video.mp4')) }}

readtime

Determines read time of a text, in minutes.

{{ readtime(value) }}

Example:

{{ readtime(page.content) }} min

hash

Calculates the hash of an object, an array or a string with a given algorithm.

{{ hash(value, algorithm) }}

algorithm can be any algorithm supported by PHP's hash() function (e.g.: md5, sha256, etc.). Default is xxh128.

Example:

{{ hash('my string', 'sha256') }}

cache_key

Calculates a cache key for fragments cache based on a name and an optional value.

{% cache cache_key(name, value) %}
  {# cacheable content #}
{% 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.

getenv

Gets the value of an environment variable from its key.

{{ getenv(var) }}

Example:

{{ getenv('VAR') }}

dump

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) }}

d

The d() function is the HTML version of dump() and use the Symfony VarDumper Component behind the scenes.

{{ d(variable, {theme: light}) }}

• If variable is not provided then the function returns the current Twig context
• Available themes are « light » (default) and « dark »

fingerprint

Add the file content finger print to the file name.

{{ asset(path)|fingerprint }}
{{ path|fingerprint }}

Examples:

{{ asset('styles.css')|fingerprint }}

minify

Minifying a CSS or a JavaScript file.

{{ asset(path)|minify }}

Examples:

{{ asset('styles.css')|minify }}
{{ asset('scripts.js')|minify }}

minify_css

Minifying a CSS string.

{{ variable|minify_css }}

{% apply minify_css %}
{# CSS here #}
{% endapply %}

Examples:

{% set styles = 'some CSS here' %}
{{ styles|minify_css }}

<style>
{% apply minify_css %}
  html {
    background-color: #fcfcfc;
    color: #444;
  }
{% endapply %}
</style>

minify_js

Minifying a JavaScript string.

{{ variable|minify_js }}

{% apply minify_js %}
{# JavaScript here #}
{% endapply %}

Examples:

{% set script = 'some JavaScript here' %}
{{ script|minify_js }}

<script>
{% apply minify_js %}
  var test = 'test';
  console.log(test);
{% endapply %}
</script>

scss_to_css

Compiles a Sass string to CSS.

{{ variable|scss_to_css }}

{% apply scss_to_css %}
{# SCSS here #}
{% endapply %}

Alias: sass_to_css.

Examples:

{% set scss = 'some SCSS here' %}
{{ scss|scss_to_css }}

<style>
{% apply scss_to_css %}
  $color: #fcfcfc;
  div {
    color: lighten($color, 20%);
  }
{% endapply %}
</style>

to_css

Compiles a Sass file to CSS.

{{ asset(path)|to_css }}
{{ path|to_css }}

Examples:

{{ asset('styles.scss')|to_css }}

inline

Outputs the content of an Asset.

{{ asset(path)|inline }}

Example:

{{ asset('styles.css')|inline }}

dataurl

Returns the data URL of an asset.

{{ asset(path)|dataurl }}
{{ asset(image_path)|dataurl }}

language

The main language, defined by its code.

language: <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:

#language: <code>
language:
  code: <code>
  prefix: true

languages

Options of available languages, used for pages and templates localization.

languages:
  - code: <code>          # unique code (e.g.: `en`, `fr`, 'en-US', `fr-CA`)
    name: <name>          # human readable name (e.g.: `Français`)
    locale: <locale>      # locale code (`language_COUNTRY`, e.g.: `en_US`, `fr_FR`, `fr_CA`)
    enabled: <true|false> # enabled or not (`true` by default)

Example:

language: en
languages:
  - code: en
    name: English
    locale: en_US
  - code: fr
    name: Français
    locale: fr_FR

Localize

To localize configuration options you must store them under the config key of the language.

Example:

title: "Cecil in english"
languages:
  - code: en
    name: English
    locale: en_US
  - code: fr
    name: Français
    locale: fr_FR
    config:
      title: "Cecil en français"

The front matter can contains custom variables applied to the current page.

It must be the first thing in the file and must be a valid YAML.

Predefined variables

updated

The updated variable is used to define the last modification date of a page.

Example:

---
updated: 2026-02-02
---

menu

A page can be added to a menu.

The 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:

---
menu: main
---

---
menu: [main, navigation] # same page in multiple menus
---

---
menu:
  main:
    weight: 10
  navigation:
    weight: 20
---

---
title: 'Our Expertise'
menu:
  main:
    weight: 15
  footer:
    weight: 15
    name: "Expertise" # override the entry name in this menu
---

Taxonomy

Taxonomy allows you to connect, relate and classify your website’s content.
In Cecil, these terms are gathered within vocabularies.

Vocabularies are declared in the Configuration.

Vocabulary

A categorization of content (e.g.: tags, categories, etc.).

Term

A term is an item of a vocabulary (e.g.: Development, PHP, etc.).

Example:

---
tags: ["Development", "PHP"]
---

Cecil then generates, for each vocabulary:

• a page listing its terms, e.g.: /tags/
• a page per term listing its pages, e.g.: /tags/development/ and /tags/php/

See templates lookup rules and taxonomy variables to customize those pages.

Schedule

Schedules pages’ publication.

Example:

The page will be published if current date is >= 2023-02-07:

schedule:
  publish: 2023-02-07

This page is published if current date is <= 2022-04-28:

schedule:
  expiry: 2022-04-28

redirect

As indicated by its name, the redirect variable is used to redirect a page to a dedicated URL.

Example:

---
redirect: "https://arnaudligny.fr"
---

alias

Alias is a redirection to the current page

Example:

---
title: "About"
alias:
  - contact
---

In the previous example contact/ redirects to about/.

output

Defines the output format of the page.

Available formats are: html, atom, rss, json, xml, etc.
You 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.

Example:

---
output: [html, atom]
---

external

A page with an external variable try to fetch the content of the pointed resource.

Example:

---
external: "https://raw.githubusercontent.com/Cecilapp/Cecil/main/README.md"
---

excluded

Set excluded to true to hide a page from list pages (i.e.: Home page, Section, Sitemap, etc.).

Example:

---
excluded: true
---

The application passes variables to the templates for manipulation in the template. Variables may have attributes or elements you can access, too.
Use a dot (.) to access attributes of a variable: {{ foo.bar }}

You can use variables from different scopes: site, page, cecil.

site

The site variable contains built-in variables and those set in the configuration.

Example:

title: "My amazing website!"

Can be displayed in a template with:

{{ site.title }}

site.menus

Loop on site.menus.<menu> to get each entry of the <menu> collection (e.g.: main).

Example:

<nav>
  <ol>
  {% for entry in site.menus.main|sort_by_weight %}
    <li><a href="{{ url(entry.url) }}" data-weight="{{ entry.weight }}">{{ entry.name }}</a></li>
  {% endfor %}
  </ol>
</nav>

site.language

Information about the current language.

site.static

The static files collection can be accessed via site.static if the static load is enabled.

Each file exposes the following properties:

• path: 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 object
• video: array of basic video information (duration in seconds, width and height)

site.data

A data collection can be accessed via site.data.<filename> (without file extension).

Examples:

• data/authors.yml : site.data.authors
• data/authors.fr.yml : site.data.authors (if site.language = "fr")
• data/galleries/gallery-1.json : site.data.galleries['gallery-1']

page

The page variable contains built-in variables of a page and those set in the front matter.

Nested sections

In a nested sections context, page.parent, page.ancestors, page.sections and page.toplevel help you build navigation.

Breadcrumb (from the home page to the current page):

<nav aria-label="breadcrumb">
  <ul>
    <li><a href="{{ url(site.home) }}">{{ site.title }}</a></li>
    {% for section in page.ancestors|reverse %}
    <li><a href="{{ url(section) }}">{{ section.title }}</a></li>
    {% endfor %}
    {% if page.id != site.home %}
    <li><a href="{{ url(page) }}" aria-current="page">{{ page.title }}</a></li>
    {% endif %}
  </ul>
</nav>

Sub-sections menu (immediate descendant sections of the current section):

{% if page.sections|length %}
<ul>
  {% for section in page.sections|sort_by_title %}
  <li><a href="{{ url(section) }}">{{ section.title }}</a></li>
  {% endfor %}
</ul>
{% endif %}

Main navigation limited to top level sections (from any page):

<nav>
  {% for section in site.page(site.home).sections|sort_by_title %}
  <a href="{{ url(section) }}">{{ section.title }}</a>
  {% endfor %}
</nav>

Link to the parent section:

{% if page.parent %}
<a href="{{ url(page.parent) }}">← {{ page.parent.title }}</a>
{% endif %}

page.<prev/next>

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.

Example:

<a href="{{ url(page.prev) }}">{{ page.prev.title }}</a>

page.paginator

Paginator helps you build navigation for list pages: homepage, sections, and taxonomies.

Example:

{% if page.paginator %}
<div>
  {% if page.paginator.links.prev is defined %}
  <a href="{{ url(page.paginator.links.prev) }}">Previous</a>
  {% endif %}
  {% if page.paginator.links.next is defined %}
  <a href="{{ url(page.paginator.links.next) }}">Next</a>
  {% endif %}
</div>
{% endif %}

Example:

{% if page.paginator %}
<div>
  {% for paginator_index in 1..page.paginator.count %}
    {% if paginator_index != page.paginator.current %}
      {% if paginator_index == 1 %}
  <a href="{{ url(page.paginator.links.first) }}">{{ paginator_index }}</a>
      {% else %}
  <a href="{{ url(page.paginator.links.path ~ '/' ~ paginator_index) }}">{{ paginator_index }}</a>
      {% endif %}
    {% else %}
  {{ paginator_index }}
    {% endif %}
  {% endfor %}
</div>
{% endif %}

Taxonomy

Variables available in vocabulary and term templates.

Vocabulary

Page /<plural>/ (e.g.: /categories/).

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.

Term

Page /<plural>/<term>/ (e.g.: /categories/php/).

Taxonomy example

Configuration:

taxonomies:
  categories: category

Page front matter:

---
categories: ["Data Sovereignty"]
---

List of terms (/categories/), in layouts/taxonomy/categories.html.twig:

{% extends 'page.html.twig' %}

{% block content %}
  <h1>{{ page.title }}</h1>
  <ul>
  {% for term in page.terms %}
    <li><a href="{{ url(term.id) }}">{{ term.name }}</a> ({{ term|length }})</li>
  {% endfor %}
  </ul>
{% endblock %}

List of pages of a term (/categories/data-sovereignty/), in layouts/taxonomy/category.html.twig:

{% extends 'page.html.twig' %}

{% block content %}
  <h1>{{ page.title }}</h1>
  {% for p in page.paginator.pages ?? page.pages %}
    <article>
      <h2><a href="{{ url(p) }}">{{ p.title }}</a></h2>
    </article>
  {% endfor %}
  <a href="{{ url(page.plural) }}">All {{ page.plural }}</a>
{% endblock %}

Links to the terms of the current page, in a page template:

{% for category in page.categories ?? [] %}
  <a href="{{ url('categories/' ~ category) }}">{{ category }}</a>
{% endfor %}

cecil

Sorting collections (of pages, menus or taxonomies).

sort_by_title

Sorts a collection by title (with natural sort).

{{ collection|sort_by_title }}

Example:

{{ site.pages|sort_by_title }}

sort_by_date

Sorts a collection by date (most recent first).

{{ collection|sort_by_date(variable='date', desc_title=false) }}

Example:

{# sort by date #}
{{ site.pages|sort_by_date }}
{# sort by updated variable instead of date #}
{{ site.pages|sort_by_date(variable='updated') }}
{# sort items with the same date by desc title #}
{{ site.pages|sort_by_date(desc_title=true) }}
{# reverse sort #}
{{ site.pages|sort_by_date|reverse }}

sort_by_weight

Sorts a collection by weight (lighter first).

{{ collection|sort_by_weight }}

Example:

{{ site.menus.main|sort_by_weight }}

sort

For more complex cases, you should use Twig’s native sort.

Example:

{% set files = site.static|sort((a, b) => a.date|date('U') < b.date|date('U')) %}

Cecil supports Markdown format, but also Markdown Extra.

Cecil also provides extra features to enhance your content, see below.

Attributes

With Markdown Extra you can set an id, class and custom attributes on certain elements using an attribute block.
For 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}

Links

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:

[Link to a path](/about/)
[Link to a Markdown file](/about/)
[Link to Cecil website](https://cecil.app)

Link to a page

You can easily create a link to a page with the syntax [Page title](page:page-id).

Example:

[Link to a blog post](page:blog/post-1)

External

By default external links have the following value for rel attribute: noopener noreferrer.

Example:

<a href="<url>" rel="noopener noreferrer">Link to another website</a>

You can change this behavior with pages.body.links.external options.

Embedded links

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:

[CECIL : LE générateur de SITES STATIQUES en PHP](https://www.youtube.com/watch?v=ur8koU0iYvc){embed}

Local video/audio files

Cecil can also create a video and audio HTML elements, through the file extension.

Example:

[Video file](video.mp4){embed controls poster=/images/video-test.png}
[Audio file](song.mp3){embed controls}

Is converted to:

<video src="/video.mp4" controls poster="/images/video-test.png" style="max-width:100%;height:auto;"></video>
<audio src="/song.mp3" controls></audio>

Images

To add an image, use an exclamation mark (!) followed by alternative description in brackets ([]), and the path or URL to the image in parentheses (()).
You can optionally add a title in quotation marks.

![Alternative description](/image.jpg "Image title")

Lazy loading

Cecil adds the attribute loading="lazy" to each image.

Example:

![](/image.jpg)

Is converted to:

<img src="/image.jpg" loading="lazy">

Decoding

Cecil adds the attribute decoding="async" to each image.

Example:

![](/image.jpg)

Is converted to:

<img src="/image.jpg" decoding="async">

Resize

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:

![](/image.jpg){width=800}

Is converted to:

<img src="/thumbnails/800/image.jpg" width="800" height="600">

Formats

If the formats option is defined, alternatives images are created and added.

Example:

![](/image.jpg)

Could be converted to:

<picture>
  <source srcset="/image.avif" type="image/avif">
  <source srcset="/image.webp" type="image/webp">
  <img src="/image.jpg">
</picture>

Responsive

If the responsive option is enabled, then all images in the body will be made responsive automatically.

Example:

![](/image.jpg){width=800}

will be converted to:

<img src="/thumbnails/800/image.jpg" width="800" height="600"
  srcset="/thumbnails/320/image.jpg 320w,
          /thumbnails/640/image.jpg 640w,
          /thumbnails/800/image.jpg 800w"
  sizes="100vw"
>

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:

assets:
  images:
    responsive:
      sizes:
        default: 100vw
        my_class: "(max-width: 800px) 768px, 1024px"

![](/image.jpg){.my_class}

CSS class

You can set a default value to the class attribute of each image with the class option.

Caption

The optional title can be used to create a caption (figcaption) automatically by enabling the caption option.

Example:

![](/images/img.jpg "Title")

Is converted to:

<figure>
  <img src="/image.jpg" title="Title">
  <figcaption>Title</figcaption>
</figure>

Localized image

For translated pages, Cecil first looks for a language-suffixed file when resolving Markdown image paths.

Example:

![](/images/cecil-logo.png)

With a French page (fr), Cecil tries /images/cecil-logo.fr.png first, then falls back to /images/cecil-logo.png.

Placeholder

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.

The placeholder attribute accepts two options:

1. color: display a colored background (based on image dominant color)
2. lqip: Low-Quality Image Placeholder

Examples:

![](/images/img.jpg){placeholder=color}
![](/images/img.jpg){placeholder=lqip}

Table of contents

You can add a table of contents with the following Markdown syntax:

[toc]

Excerpt

An excerpt can be defined in the body with one of those following tags: excerpt or break.

Example:

Introduction.
<!-- excerpt -->
Main content.

Then use the excerpt_html filter in your template.

Notes

Create a Note block (info, tips, important, etc.).

Example:

:::tip
**Tip:** This is advice.
:::

Is converted to:

<aside class="note note-tip">
  <p>
    <strong>Tip:</strong> This is advice.
  </p>
</aside>

Others examples:

Syntax highlight

Code block syntax highlighting is enabled by default with the pages.body.highlight option.

If needed, you can disable it with:

pages:
  body:
    highlight: false

Example:

```php
echo "Hello world";
```

Is rendered to:

echo "Hello world";

Inserted text

Represents a range of text that has been added.

++text++

Is converted to:

<ins>text</ins>

File system tree

Project files organization.

<mywebsite>
├─ pages
|  ├─ blog            <- Section
|  |  ├─ post-1.md    <- Page in Section
|  |  └─ post-2.md
|  ├─ projects
|  |  └─ project-a.md
|  └─ about.md        <- Root page
├─ assets
|  ├─ styles.scss     <- Asset file
|  └─ logo.png
├─ static
|  └─ file.pdf        <- Static file
└─ data
   └─ authors.yml     <- Data collection

Built website tree

Result of the build.

<mywebsite>
└─ _site
   ├─ index.html               <- Generated home page
   ├─ blog/
   |  ├─ index.html            <- Generated list of posts
   |  ├─ post-1/index.html     <- A blog post
   |  └─ post-2/index.html
   ├─ projects/
   |  ├─ index.html
   |  └─ project-a/index.html
   ├─ about/index.html
   ├─ styles.css
   ├─ logo.png
   └─ file.pdf

File based routing

Markdown 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:
                   pages/my-projects/project-a.md
                        └───── filepath ──────┘
URL:
    ┌───── baseurl ─────┬─────── path ────────┐
     https://example.com/my-projects/project-a/index.html
                        └─ 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 }}

filter_by

Filters a pages collection by variable name/value.

{{ collection|filter_by(variable, value) }}

Example:

{{ pages|filter_by('section', 'blog') }}

filter

For more complex cases, you should use Twig’s native filter.

Example:

{% pages|filter(p => p.virtual == false and p.id not in ['page-1', 'page-2']) %}

markdown_to_html

Converts a Markdown string to HTML.

{{ markdown|markdown_to_html }}

{% apply markdown_to_html %}
{# Markdown here #}
{% endapply %}

Examples:

{% set markdown = '**This is bold text**' %}
{{ markdown|markdown_to_html }}

{% apply markdown_to_html %}
**This is bold text**
{% endapply %}

toc

Extracts only headings matching the given selectors (h2, h3, etc.), or those defined in config pages.body.toc if not specified.
The format parameter defines the output format: html or json.
The url parameter is used to build links to headings.

{{ markdown|toc(format, selectors, url) }}

Examples:

{{ page.body|toc }}
{{ page.body|toc('html') }}
{{ page.body|toc(selectors=['h2']) }}
{{ page.body|toc(url=url(page)) }}

json_decode

Converts a JSON string to an array.

{{ json|json_decode }}

Example:

{% set json = '{"foo": "bar"}' %}
{% set array = json|json_decode %}
{{ array.foo }}

yaml_parse

Converts a YAML string to an array.

{{ yaml|yaml_parse }}

Example:

{% set yaml = 'key: value' %}
{% set array = yaml|yaml_parse %}
{{ array.key }}

slugify

Converts a string to a slug.

{{ string|slugify }}

u

The u filter wraps a text in a Unicode object (a Symfony UnicodeString instance) that exposes methods to "manipulate" the string.

Example:

{{ 'cecil_string with twig'|u.camel.title }}

CecilStringWithTwig

singular

The singular filter transforms a given noun in its plural form into its singular version.

{{ string|singular(locale)}}

Example:

{# English (en) rules are used by default #}
{{ 'partitions'|singular }}

partition

{{ 'partitions'|singular('fr') }}

partition

plural

The plural filter transforms a given noun in its singular form into its plural version.

{{ string|plural(locale)}}

Example:

{# English (en) rules are used by default #}
{{ 'animal'|plural }}

animals

{{ 'animal'|plural('fr') }}

animaux

excerpt

Truncates a string and appends suffix.

{{ string|excerpt(length, suffix) }}

Examples:

{{ variable|excerpt }}
{{ variable|excerpt(250, '...') }}

excerpt_html

Reads characters before or after <!-- excerpt --> or <!-- break --> tag.
See Content documentation for details.

{{ string|excerpt_html({separator, capture}) }}

Examples:

{{ variable|excerpt_html }}
{{ variable|excerpt_html({separator: 'excerpt|break', capture: 'before'}) }}
{{ variable|excerpt_html({capture: 'after'}) }}

highlight

Highlights a code string with highlight.php.

{{ code|highlight(language) }}

Examples:

{{ '<?php echo $highlighted->value; ?>'|highlight('php') }}

preg_split

Splits a string into an array using a regular expression.

{{ string|preg_split(pattern, limit) }}

Example:

{% set headers = page.content|preg_split('/<br[^>]*>/') %}

preg_match_all

Performs a regular expression match and return the group for all matches.

{{ string|preg_match_all(pattern, group) }}

Example:

{% set tags = page.content|preg_match_all('/<[^>]+>(.*)<\/[^>]+>/') %}

hex_to_rgb

Converts a hexadecimal color to RGB.

{{ color|hex_to_rgb }}

pages.dir

Directory source of pages (pages by default).

pages:
  dir: pages

pages.ext

Extensions of pages files.

pages:
  ext: [md, markdown, mdown, mkdn, mkd, text, txt]

pages.exclude

Directories, paths and files name to exclude (accepts globs, strings and regexes).

pages:
  exclude: ['vendor', 'node_modules', '*.scss', '/\.bck$/']

pages.prefix.separator

List of characters used as separator between a filename prefix (date or weight) and the slug.

pages:
  prefix:
    separator: ['-', '_']

pages.sortby

Default collections sort method.

pages:
  sortby: date # `date`, `updated`, `title` or `weight`
  # or
  sortby:
    variable: date    # `date`, `updated`, `title` or `weight`
    desc_title: false # sort by title in descending order
    reverse: false    # reverse the sort order

pages.pagination

Pagination is available for list pages (type is homepage, section or term).

pages:
  pagination:
    max: 5     # maximum number of entries per page
    path: page # path to the paginated page

Disable pagination

Pagination can be disabled:

pages:
  pagination: false

pages.paths

Apply a custom path for all pages of a Section.

pages:
  paths:
    - section: <section’s ID>
      path: <path of pages>

Path placeholders

• :year
• :month
• :day
• :section
• :slug

Example:

pages:
  paths:
    - section: Blog
      path: :section/:year/:month/:day/:slug # e.g.: /blog/2020/12/01/my-post/
# localized
languages:
  - code: fr
    name: Français
    locale: fr_FR
    config:
      pages:
        paths:
          - section: Blog
            path: blogue/:year/:month/:day/:slug # e.g.: /blogue/2020/12/01/mon-billet/

pages.frontmatter

Page front matter format (yaml by default, also accepts ini, toml and json).

pages:
  frontmatter: yaml

pages.body

Page body options.

pages.body.toc

Headers used to build the table of contents ([h2, h3] by default).

pages:
  body:
    toc: [h2, h3]

pages.body.highlight

Enables code syntax highlighting (true by default).

pages:
  body:
    highlight: false # set to false to disable syntax highlighting

pages.body.images

Images handling options.

pages:
  body:
    images:
      formats: []       # adds alternative image formats as `source` (e.g. `[avif, webp]`, empty array by default)
      resize: 0         # resizes all images to <width> (in pixels, `0` to disable)
      responsive: false # adds responsive image variants to the `srcset` attribute (`false` by default)
      lazy: true        # adds `loading="lazy"` attribute (`true` by default)
      decoding: true    # adds `decoding="async"` attribute (`true` by default)
      caption: false    # puts the image in a <figure> element and adds a <figcaption> containing the title (`false` by default)
      placeholder: ''   # fills the <img> background before loading ('color' or 'lqip', empty by default)
      class: ''         # sets a default class on each image (empty by default)
      dark_suffix: ''   # suffix of the dark variant image (e.g. `.dark`), disabled by default
      mobile_suffix: '' # suffix of the mobile variant image (e.g. `.mobile`), disabled by default
      mobile_media_query: '(max-width: 767px)' # media query of the mobile variant `<source>`
      remote:           # remote image handling (set to `false` to disable)
        fallback:         # path to the fallback image, stored in assets dir (empty by default)

pages.body.links

Links handling options.

pages:
  body:
    links:
      embed:
        enabled: false     # turns links in embedded content if possible (`false` by default)
        video: [mp4, webm] # video files extensions
        audio: [mp3]       # audio files extensions
      external:
        blank: false     # if true open external link in new tab
        noopener: true   # if true add "noopener" to `rel` attribute
        noreferrer: true # if true add "noreferrer" to `rel` attribute
        nofollow: false  # if true add "nofollow" to `rel` attribute

pages.body.excerpt

Excerpt handling options.

pages:
  body:
    excerpt:
      separator: excerpt|break # string to use as separator (`excerpt|break` by default)
      capture: before          # part to capture, `before` or `after` the separator (`before` by default)

pages.virtual

Virtual pages is the best way to create pages without content (front matter only).

It consists of a list of pages with a path and some front matter variables.

Example:

pages:
  virtual:
    - path: code
      redirect: https://github.com/ArnaudLigny

pages.default

Default pages are pages created automatically by Cecil (from built-in templates):

pages:
  default:
    index:
      path: ''
      title: Home
      published: true
    404:
      path: 404
      title: Page not found
      layout: 404
      uglyurl: true
      published: true
      excluded: true
    robots:
      path: robots
      title: Robots.txt
      layout: robots
      output: txt
      published: true
      excluded: true
      multilingual: false
    sitemap:
      path: sitemap
      title: XML sitemap
      layout: sitemap
      output: xml
      changefreq: monthly
      priority: 0.5
      published: true
      excluded: true
      multilingual: false
    xsl/atom:
      path: xsl/atom
      layout: feed
      output: xsl
      uglyurl: true
      published: true
      excluded: true
    xsl/rss:
      path: xsl/rss
      layout: feed
      output: xsl
      uglyurl: true
      published: false
      excluded: true

Each one can be:

1. disabled: published: false
2. excluded from list pages: excluded: true
3. excluded from localization: multilingual: false

pages.generators

Generators 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.

Below the list of Generators provided by Cecil, in a defined order:

pages:
  generators:
    10: 'Cecil\Generator\DefaultPages'
    20: 'Cecil\Generator\VirtualPages'
    30: 'Cecil\Generator\ExternalBody'
    40: 'Cecil\Generator\Section'
    50: 'Cecil\Generator\Taxonomy'
    60: 'Cecil\Generator\Homepage'
    70: 'Cecil\Generator\Pagination'
    80: 'Cecil\Generator\Alias'
    90: 'Cecil\Generator\Redirect'

pages.subsets

Subsets are used to render a part of the pages collection, based on a specific path, language or output format, with the command:

cecil build --render-subset=<name>

pages:
  subsets:
    <name>:
      path: <path> # glob or string path (e.g.: `blog/*`, `blog`)
      language: <language> # language code (e.g.: `en`, `fr`)
      output: <output> # output format (e.g.: `html`, `atom`)

Example:

pages:
  subsets:
    blog_en:
      path: blog
      language: en
      output: html
    search_index:
      path: '*'
      output: json

If your pages are available in multiple languages there is 2 different ways to define it:

Through file name

This is the common way to translate a page from the main language to another language.

You just need to duplicate the reference page and suffix it with the target language code (e.g.: fr).

Example:

├─ about.md    # the reference page
└─ about.fr.md # the french version (`fr`)

Through front matter

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:

---
language: fr
---

Link translated pages

Each translated page reference the pages in others languages.

Those pages collection is available in templates with the following variable:

{{ page.translations }}

Cecil provides a components logic to give you the power making reusable template "units".

Components syntax

Components are just Twig templates stored in the components/ subdirectory and can be used anywhere in your templates:

{# /components/button.twig #}
<button {{ attributes.merge({class: 'rounded px-4'}) }}>
    {{ slot }}
</button>

The slot variable is any content you will add between the opening and the close tag.

To reach a component you need to use the dedicated tag x followed by : and the filename of your component without extension:

{# /index.twig #}
{% x:button with {class: 'text-white'} %}
    <strong>Click me</strong>
{% endx %}

It will render:

<button class="text-white rounded px-4">
    <strong>Click me</strong>
</button>

Data

Where data files are stored and what extensions are handled.

Supported formats: YAML, JSON, XML and CSV.

data.dir

Data source directory (data by default).

data:
  dir: data

data.ext

Array of files extensions.

data:
  ext: [yaml, yml, json, xml, csv]

data.load

Enables site.data collection (true by default).

data:
  load: true

Static

Management of static files are copied (PDF, fonts, etc.).

static.dir

Static files source directory (static by default).

static:
  dir: static

static.target

Directory where static files are copied (root by default).

static:
  target: ''

static.exclude

List of excluded files. Accepts globs, strings and regexes.

static:
  exclude: ['sass', 'scss', '*.scss', 'package*.json', 'node_modules']

static.load

Enables site.static collection (false by default).

static:
  load: false

static.mounts

Allows to copy specific files or directories to a specific destination.

static:
  mounts: []

static example

static:
  dir: docs
  target: docs
  exclude: ['sass', '*.scss', '/\.bck$/']
  load: true
  mounts:
    - source/path/file.ext: dest/path/file.ext
    - node_modules/bootstrap-icons/font/fonts: fonts

You can create dynamic content in a page by using the template_from_string Twig function.

{{ 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.

--
var: 'value'
---
The value of `var` is {{ page.var }}.

Cecil support text translation and date localization.

Text translation

Uses the trans tag or filter to translate texts in templates.

{% trans with variables into locale %}{% endtrans %}

{{ message|trans(variables = []) }}

Examples

{% trans %}Hello World!{% endtrans %}

{{ message|trans }}

Include variables:

{% trans with {'%name%': 'Arnaud'} %}Hello %name%!{% endtrans %}

{{ message|trans({'%name%': 'Arnaud'}) }}

Force locale:

{% trans into 'fr_FR' %}Hello World!{% endtrans %}

Pluralize:

{% trans with {'%count%': 42}%}{0}I don't have apples|{1}I have one apple|]1,Inf[I have %count% apples{% endtrans %}

Translation files

Translation files must be named messages.<locale>.<extension> and stored in the translations directory.
Supported 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:

<mywebsite>
└─ translations
   ├─ messages.fr_FR.mo   <- Machine Object format
   └─ messages.fr_FR.yaml <- Yaml format

Date localization

Uses the Twig format_date filter to localize a date in templates.

{{ page.date|format_date('long') }}
{# September 30, 2022 #}

Supported values are: short, medium, long, and full.

Assets management (images, CSS and JS files).

assets.dir

Assets source directory (assets by default).

assets:
  dir: assets

assets.target

Directory where remote and resized assets files are saved (root by default).

assets:
  target: ''

assets.fingerprint

Enables fingerprinting (cache busting) for assets files (true by default).

assets:
  fingerprint: true

assets.compile

Enables Sass files compilation (true by default). See the documentation of scssphp for options details.

assets:
  compile:
    style: expanded      # compilation style (`expanded` or `compressed`. `expanded` by default)
    import: [sass, scss] # list of imported paths (`[sass, scss, node_modules]` by default)
    sourcemap: false     # enables sourcemap in debug mode (`false` by default)
    variables: []        # list of preset variables (empty by default)

assets.minify

Enables CSS and JS minification (true by default).

assets:
  minify: true

assets.images

Images management.

assets:
  images:
    optimize: false # enables images optimization with JpegOptim, Optipng, Pngquant 2, SVGO 1, Gifsicle, cwebp, avifenc (`false` by default)
    quality: 75     # image quality of `optimize` and `resize` (`75` by default)
    responsive:
      widths: [480, 640, 768, 1024, 1366, 1600, 1920] # `srcset` attribute images widths
      sizes:
        default: '100vw' # default `sizes` attribute (`100vw` by default)

assets.images.cdn

URL of image assets can be easily replaced by a provided CDN url.

assets:
  images:
    cdn:
      enabled: false  # enables Image CDN (`false` by default)
      canonical: true # `image_url` is canonical (instead of a relative path) (`true` by default)
      remote: true    # handles not local images too (`true` by default)
      account: 'xxxx' # provider account
      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 format

See CDN providers.

assets.remote.useragent

User agent used to download remote assets.

assets:
  remote:
    useragent:
      default: <string> # default user agent
      useragent1: <string>
      useragent2: <string>

Cecil uses a cache system to speed up the generation process, it can be disabled or cleared.

There are three cache types involved in template rendering: templates, assets, and translations.

Clear cache

You can clear the cache with the following commands:

php cecil.phar cache:clear               # clear all caches
php cecil.phar cache:clear:assets        # clear assets cache
php cecil.phar cache:clear:templates     # clear templates cache
php cecil.phar cache:clear:translations  # clear translations cache

Fragments cache

Cecil provides a way to cache parts of templates rendering to avoid re-rendering the same partial content multiple times.

To use fragments cache, you must wrap the content you want to cache with the cache tag.

{% cache 'unique-key' %}
  {# cacheable content #}
{% endcache %}

To clear fragments cache only, you can use the following command:

php cecil.phar cache:clear:templates --fragments

Disable cache

You can disable cache with the configuration.

Templates options.

layouts.dir

Templates directory source (layouts by default).

layouts:
  dir: layouts

layouts.autoescape

Overrides 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 -> html
• any other extension -> false

layouts:
  autoescape: false  # disables automatic escaping (default) 
  #autoescape: null  # use Cecil automatic strategy by template filename extension 
  #autoescape: html
  #autoescape: js

layouts.images

Images handling options.

layouts:
  images:
    formats: []       # used by `html` function: adds alternatives image formats as `source` (e.g. `[avif, webp]`, empty array by default)
    responsive: false # used by `html` function: adds responsive images ('width' or 'density', `false` by default)
    placeholder: ''   # used by `html` function: fills image background before loading (`color` or `lqip`, disabled by default)
    dark_suffix: ''   # suffix of the dark variant image (e.g. `.dark`), disabled by default
    mobile_suffix: '' # suffix of the mobile variant image (e.g. `.mobile`), disabled by default
    mobile_media_query: '(max-width: 767px)' # media query of the mobile variant `<source>`

layouts.translations

Translations handling options.

layouts:
  translations:
    dir: translations # translations source directory (`translations` by default)
    formats:          # translations supported formats
      yaml:
        loader: Symfony\Component\Translation\Loader\YamlFileLoader
        ext: [yml, yaml]
      mo:
        loader: Symfony\Component\Translation\Loader\MoFileLoader
        ext: [mo]

Each translation format defines:

• loader: Symfony translation loader class
• ext: one or more file extensions associated with this format

layouts.components

Templates Components options.

layouts:
  components:
    dir: components # components source directory (`components` by default)
    ext: twig       # components files extension (`twig` by default)

layouts.sections

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:
  sections:
    news: blog # the "news" section is rendered with `blog/list.html.twig` and its pages with `blog/page.html.twig`

Functions and filters

You can add custom functions and custom filters with a Twig extension.

Theme

It’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>
└─ themes
   └─ <theme>
      ├─ config.yml
      ├─ assets
      ├─ layouts
      ├─ static
      └─ translations

Defines where and in what format pages are rendered.

output.dir

Directory where rendered pages’ files are saved (_site by default).

output:
  dir: _site

output.formats

List of output formats definition, which are used to render pages (e.g. HTML, Atom, RSS, JSON, XML, etc.).

output:
  formats:
    - name: <name>            # name of the format, e.g.: `html` (required)
      mediatype: <media type> # media type (MIME type), ie: 'text/html' (optional)
      subpath: <sub path>     # sub path, e.g.: `amp` in `path/amp/index.html` (optional)
      filename: <file name>   # file name, e.g.: `index` in `path/index.html` (optional)
      extension: <extension>  # file extension, e.g.: `html` in `path/index.html` (required)
      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.

Default formats

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.

output.pagetypeformats

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:
  pagetypeformats:
    page: [<format>]
    homepage: [<format>]
    section: [<format>]
    vocabulary: [<format>]
    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:
  pagetypeformats:
    section: [html, atom]

output example

output:
  dir: _site
  formats:
    - name: html
      mediatype: text/html
      filename: index
      extension: html
    - name: atom
      mediatype: application/xml
      filename: atom
      extension: xml
      exclude: [redirect, paginated]
  pagetypeformats:
    page: [html]
    homepage: [html, atom]
    section: [html, atom]
    vocabulary: [html]
    term: [html, atom]

Post process

You can extend Cecil capabilities with an Output post processor to modify the output files after they have been generated.

Cache options.

cache.enabled

Cache is enabled by default (true), but you can disable it with:

cache:
  enabled: false

cache.dir

Directory where cache files are stored (.cache by default).

cache:
  dir: '.cache'

cache.assets

Assets cache options.

cache.assets.ttl

Time to live of assets cache in seconds (null by default = no expiration).

cache:
  assets:
    ttl: ~

cache.assets.remote.ttl

Time to live of remote assets cache in seconds (7 days by default).

cache:
  assets:
    remotes:
      ttl: 604800 # 7 days

cache.templates

Disables templates cache with false (true by default).

cache:
  templates: true

cache.translations

Disables translations cache with false (true by default).

cache:
  translations: true

Server

server.headers

You can define custom HTTP headers, used by the local preview server.

server:
  headers:
    - path: <path> # Relative path, prefixed with a slash. Support "*" wildcard.
      headers:
        - key: <key>
          value: "<value>"

Example:

server:
  headers:
    - path: /*
      headers:
        - key: X-Frame-Options
          value: "SAMEORIGIN"
        - key: X-XSS-Protection
          value: "1; mode=block"
        - key: X-Content-Type-Options
          value: "nosniff"
        - key: Content-Security-Policy
          value: "default-src 'self'; object-src 'self'; img-src 'self'"
        - key: Strict-Transport-Security
          value: "max-age=31536000; includeSubDomains; preload"
    - path: /assets/*
      headers:
        - key: Cache-Control
          value: "public, max-age=31536000"
    - path: /foo.html
      headers:
        - key: Foo
          value: "bar"

Optimize

The optimization options allow to enable compression of output files: HTML, CSS, JavaScript and image.

optimize:
  enabled: false     # enables files optimization (`false` by default)
  html:
    enabled: true    # enables HTML files optimization
    ext: [html, htm]   # supported files extensions
  css:
    enabled: true    # enables CSS files optimization
    ext: [css]         # supported files extensions
  js:
    enabled: true    # enables JavaScript files optimization
    ext: [js]          # supported files extensions
  images:
    enabled: true    # enables images files optimization
    ext: [jpeg, jpg, png, gif, webp, svg, avif] # supported files extensions

This option is disabled by default and can be enabled via:

optimize: true

Once the global option is enabled, the 4 file types will be processed.
It is possible to disable each of them via enabled: false and modify processed files extension via ext.

Environment variables

The configuration can be overridden through environment variables.

At startup, Cecil also attempts to load a .env file from the current site path (the current working directory, or the <path> argument if provided).

• If the .env file does not exist, Cecil continues normally.
• Variables already defined by the shell/system are preserved.

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/"
CECIL_TITLE="My Cecil site"

CLI option

You can combine multiple configuration files, with the --config option (left-to-right precedence):

php cecil.phar --config config-1.yml,config-2.yml

Creates a new site.

Description:
  Creates a new website

Usage:
  new:site [options] [--] [<path>]

Arguments:
  path                  Use the given path as working directory

Options:
  -f, --force           Override directory if it already exists
      --demo            Add demo content (pages, templates and assets)
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The new:site command creates a new website in the current directory, or in <path> if provided.
  If you run this command without any options, it will ask you for the website title, baseline, base URL, description, etc.

    cecil.phar new:site
    cecil.phar new:site path/to/the/working/directory

  To create a new website with demo content, run:

    cecil.phar new:site --demo

  To override an existing website, run:

    cecil.phar new:site --force

Netlify

A powerful serverless platform with an intuitive git-based workflow. Automated deployments, shareable previews, and much more.

➡️ https://www.netlify.com

netlify.toml:

[build]
  publish = "_site"
  command = "curl -sSOL https://cecil.app/build.sh && bash ./build.sh"
[context.production.environment]
  CECIL_ENV = "production"
[context.deploy-preview.environment]
  CECIL_ENV = "preview"

Official documentation

Vercel

Vercel combines the best developer experience with an obsessive focus on end-user performance.

➡️ https://vercel.com

vercel.json:

{
  "buildCommand": "curl -sSOL https://cecil.app/build.sh && bash ./build.sh",
  "outputDirectory": "_site"
}

Official documentation

statichost

Modern static site hosting with European servers and absolutely no personal data collection!

➡️ https://statichost.eu

statichost.yml:

image: wordpress:cli-php8.4
command: curl -sSOL https://cecil.app/build.sh && bash ./build.sh
public: _site

Official documentation

Cloudflare Pages

Cloudflare Pages is a JAMstack platform for frontend developers to collaborate and deploy websites.

➡️ https://pages.cloudflare.com

Build configurations:

• Framework preset: None
• Build command: curl -sSOL https://cecil.app/build.sh && bash ./build.sh
• Build output directory: _site

Official documentation

Render

Render 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.

➡️ https://render.com

render.yaml:

previewsEnabled: true
services:
  - type: web
    name: Cecil
    env: static
    buildCommand: curl -sSOL https://cecil.app/build.sh && bash ./build.sh
    staticPublishPath: _site
    pullRequestPreviewsEnabled: true

Official documentation

Create a website

You can create a new website from scratch in a few minutes.

Follow the steps below to create your first Cecil website.

Prerequisites

• PHP 8.3+
• Terminal (a basic understanding of terminal)
• Text editor, like VS Code and/or Typora

1. Download Cecil

Download cecil.phar from your terminal:

curl -LO https://cecil.app/cecil.phar

You can also download Cecil manually, or use:

• Homebrew: brew install cecilapp/tap/cecil
• Scoop: scoop install https://cecil.app/scoop/cecil.json

2. Create a new site

Create a directory for the website (e.g.: <mywebsite>), put cecil.phar in it, then run the new:site command:

php cecil.phar new:site

3. Add a page

Run the new:page command:

php cecil.phar new:page

Now you can edit the newly created page with your Markdown editor: <mywebsite>/pages/<new-page>.md.

4. Check the preview

Run the following command to create a preview of the website:

php cecil.phar serve

Then navigate to http://localhost:8000.

5. Build and deploy

When you are satisfied with the result, you can generate the website in order to deploy it on the Web.

Run the following command to build the website:

php cecil.phar build

You can now copy the content of the _site directory to a Web server 🎉

Creates a new page.

Description:
  Creates a new page

Usage:
  new:page [options] [--] [<path>]

Arguments:
  path                        Use the given path as working directory

Options:
      --name=NAME             Page path name
      --slugify|--no-slugify  Slugify file name (or disable --no-slugify)
  -p, --prefix                Prefix the file name with the current date (`YYYY-MM-DD`)
  -f, --force                 Override the file if already exist
  -o, --open                  Open editor automatically
      --editor=EDITOR         Editor to use with open option
  -h, --help                  Display help for the given command. When no command is given display help for the list command
  -q, --quiet                 Do not output any message
  -V, --version               Display this application version
      --ansi|--no-ansi        Force (or disable --no-ansi) ANSI output
  -n, --no-interaction        Do not ask any interactive question
  -v|vv|vvv, --verbose        Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The new:page command creates a new page file.
  If you run this command without any options, it will ask you for the page name and other options.

    cecil.phar new:page
    cecil.phar new:page --name=path/to/a-page.md
    cecil.phar new:page --name=path/to/A Page.md --slugify

  To create a new page with a date prefix (i.e: `YYYY-MM-DD`), run:

    cecil.phar new:page --prefix

  To create a new page and open it with an editor, run:

    cecil.phar new:page --open --editor=editor

  To override an existing page, run:

    cecil.phar new:page --force

Page’s models

You can define your own models for your new pages in the models directory:

1. The name must be based on the section’s name (e.g.: blog.md)
2. The default model must be named default.md (for root pages or pages’s section without model)

Two dynamic variables are available:

1. %title%: the file’s name
2. %date%: the current date

Open with your editor

With 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).

GitHub Pages

Websites for you and your projects, hosted directly from your GitHub repository. Just edit, push, and your changes are live.

➡️ https://pages.github.com

.github/workflows/build-and-deploy.yml:

name: Build and deploy to GitHub Pages
on:
  push:
    branches: [master, main]
  workflow_dispatch:
concurrency:
  group: pages
  cancel-in-progress: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v6
      - name: Restore Cecil cache
        uses: actions/cache/restore@v5
        with:
          path: ./.cache
          key: cecil-cache-
          restore-keys: |
            cecil-cache-
      - name: Build site
        uses: Cecilapp/Cecil-Action@v4
      - name: Save Cecil cache
        uses: actions/cache/save@v5
        with:
          path: ./.cache
          key: cecil-cache-${{ hashFiles('./.cache/**/*') }}
  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

Official documentation

GitLab CI

With GitLab Pages, you can publish static websites directly from a repository in GitLab.

➡️ https://about.gitlab.com/solutions/continuous-integration/

.gitlab-ci.yml:

image: wordpress:cli-php8.4
test:
  stage: test
  variables:
    CECIL_OUTPUT_DIR: test
  script:
    - curl -sSOL https://cecil.app/build.sh && bash ./build.sh
  artifacts:
    paths:
     - test
  except:
   - master
pages:
  stage: deploy
  variables:
    CECIL_ENV: production
    CECIL_OUTPUT_DIR: public
  script:
    - curl -sSOL https://cecil.app/build.sh && bash ./build.sh
  artifacts:
    paths:
      - public
  only:
    - master
cache:
  paths:
    - composer-cache/
    - vendor/
    - .cache/

Official documentation

Builds and serves the site locally.

Description:
  Starts the built-in server

Usage:
  serve [options] [--] [<path>]

Arguments:
  path                             Use the given path as working directory

Options:
  -o, --open                       Open web browser automatically
      --host=HOST                  Server host [default: "localhost"]
      --port=PORT                  Server port [default: "8000"]
  -w, --watch|--no-watch           Enable (or disable --no-watch) changes watcher (enabled by default)
  -i, --incremental                Enable incremental builds (rebuild only changed pages)
  -d, --drafts                     Include drafts
      --optimize|--no-optimize     Enable (or disable --no-optimize) optimization of generated files
  -c, --config=CONFIG              Set the path to extra config files (comma-separated)
      --clear-cache[=CLEAR-CACHE]  Clear cache before build (optional cache key as regular expression) [default: false]
  -p, --page=PAGE                  Build a specific page
      --no-ignore-vcs              Changes watcher must not ignore VCS directories
  -m, --metrics                    Show build metrics (duration and memory) of each step
      --timeout=TIMEOUT            Sets the process timeout (max. runtime) in seconds [default: 7200]
      --notify                     Send desktop notification on server start
  -b, --background                 Run the server in the background
  -h, --help                       Display help for the given command. When no command is given display help for the list command
  -q, --quiet                      Do not output any message
  -V, --version                    Display this application version
      --ansi|--no-ansi             Force (or disable --no-ansi) ANSI output
  -n, --no-interaction             Do not ask any interactive question
  -v|vv|vvv, --verbose             Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The serve command starts the live-reloading-built-in web server.

    cecil.phar serve
    cecil.phar serve path/to/the/working/directory
    cecil.phar serve --open
    cecil.phar serve --drafts
    cecil.phar serve --no-watch

  To speed up local development you can enable incremental builds with the --incremental option.
  When content pages change, Cecil rebuilds just those pages.
  When templates change, Cecil rebuilds only pages using those templates (including Twig dependencies such as extends/include).
  Any other change (data, config, static or asset file, or file deletion) triggers a full rebuild:

    cecil.phar serve --incremental

  You can use a custom host and port by using the --host and --port options:

    cecil.phar serve --host=127.0.0.1 --port=8080

  To build the website with an extra configuration file, you can use the --config option.
  This is useful during local development to override some settings without modifying the main configuration:

    cecil.phar serve --config=config/dev.yml

  To start the server with changes watcher not ignoring VCS directories, run:

    cecil.phar serve --no-ignore-vcs

  To define the process timeout (in seconds), run:

    cecil.phar serve --timeout=7200

  To run the server in the background, run:

    cecil.phar serve --background
    cecil.phar serve -b

  Then stop it with:

    cecil.phar serve:stop

  In background mode, file changes are not watched automatically.

serve:background

Alias of serve --background: starts the built-in server in the background without occupying the terminal.

Description:
  Starts the built-in server in the background (alias of `serve --background`)

Usage:
  serve:background [options] [--] [<path>]

Help:
  The serve:background command starts the built-in web server in the background.

    cecil.phar serve:background
    cecil.phar serve:background path/to/the/working/directory

  This command is an alias of serve --background.

  Stop the server with:

    cecil.phar serve:stop

serve:log

Displays the combined server and error logs.

Description:
  Shows combined server and error logs

Usage:
  serve:log [options] [--] [<path>]

Arguments:
  path                  Use the given path as working directory

Options:
  -l, --lines=LINES     Number of entries to display (default: 25)

Help:
  The serve:log command displays entries from combined server and error logs, sorted by date.

    cecil.phar serve:log
    cecil.phar serve:log path/to/the/working/directory
    cecil.phar serve:log --lines=100
    cecil.phar serve:log -l 100

  This command shows logs from `.cecil/errors.log` and `.cecil/server.log`.
  It is useful for debugging issues with your local development server.

Available locale codes (language_COUNTRY) used by the languages option.

Surge

Shipping web projects should be fast, easy, and low risk. Surge is static web publishing for Front-End Developers, right from the CLI.

➡️ https://surge.sh

Terminal:

npm install -g surge
surge _site/

Official documentation

Builds the site.

Description:
  Builds the website

Usage:
  build [options] [--] [<path>]

Arguments:
  path                               Use the given path as working directory

Options:
  -d, --drafts                       Include drafts
  -u, --baseurl=BASEURL              Set the base URL
  -o, --output=OUTPUT                Set the output directory
      --optimize|--no-optimize       Enable (or disable --no-optimize) optimization of generated files
      --dry-run                      Build without saving
  -c, --config=CONFIG                Set the path to extra config files (comma-separated)
      --clear-cache[=CLEAR-CACHE]    Clear cache before build (optional cache key as regular expression) [default: false]
  -p, --page=PAGE                    Build a specific page
      --render-subset=RENDER-SUBSET  Render a subset of pages
      --show-pages                   Show list of built pages in a table
  -m, --metrics                      Show build metrics (duration and memory) of each step
      --notify                       Send desktop notification on build completion
  -h, --help                         Display help for the given command. When no command is given display help for the list command
  -q, --quiet                        Do not output any message
  -V, --version                      Display this application version
      --ansi|--no-ansi               Force (or disable --no-ansi) ANSI output
  -n, --no-interaction               Do not ask any interactive question
  -v|vv|vvv, --verbose               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The build command generates the website in the output directory.

    cecil.phar build
    cecil.phar build path/to/the/working/directory
    cecil.phar build --baseurl=https://example.com/
    cecil.phar build --output=_site

  To build the website with optimization of generated files, you can use the --optimize option.
  This is useful to reduce the size of the generated files and improve performance:

    cecil.phar build --optimize
    cecil.phar build --no-optimize

  To build the website without overwriting files in the output directory, you can use the --dry-run option.
  This is useful to check what would be built without actually writing files:

    cecil.phar build --dry-run

  To build the website with a specific subset of rendered pages, you can use the --render-subset option.
  This is useful to build only a part of the website, for example, only "hot" pages or a specific section:

    cecil.phar build --render-subset=subset

  To show build steps metrics, run:

    cecil.phar build --metrics

To get started quickly, use one of Cecil's ready-to-use starter kits:

• The Butler: a publishing-ready starter blog.
• Links: an open source Linktree alternative.
• Photo Stream: a super simple self-hosted photo stream.
• Statidocs: build a documentation website quickly.

Diagnoses the current site and Cecil environment.

Description:
  Diagnoses the site configuration

Usage:
  doctor [options] [--] [<path>]

Arguments:
  path                       Use the given path as working directory

Options:
  -c, --config=CONFIG        Set the path to an extra configuration file
  -h, --help                 Display help for the given command. When no command is given display help for the list command
  -q, --quiet                Do not output any message
  -V, --version              Display this application version
      --ansi|--no-ansi       Force (or disable --no-ansi) ANSI output
  -n, --no-interaction       Do not ask any interactive question
  -v|vv|vvv, --verbose       Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The doctor command diagnoses the current site and Cecil environment.

    cecil.phar doctor
    cecil.phar doctor path/to/the/working/directory

  To inspect a site with an extra configuration file, run:

    cecil.phar doctor --config=config.yml

doctor:frontmatter

Validates pages front matter syntax.

Description:
  Validates pages front matter syntax

Usage:
  doctor:frontmatter|doctor:fm [options] [--] [<path>]

Arguments:
  path                  Use the given path as working directory

Options:
  -c, --config=CONFIG   Set the path to an extra configuration file
  -p, --page=PAGE       Validate a single page relative to the pages directory
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
  -v|vv|vvv             Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

doctor:seo

Audits rendered HTML pages for common SEO issues.

Description:
  Audits rendered HTML pages for common SEO issues

Usage:
  doctor:seo [options] [--] [<path>]

Arguments:
  path                  Use the given path as working directory

Options:
  -c, --config=CONFIG   Set the path to an extra configuration file
  -p, --page=PAGE       Audit a single page relative to the pages directory
      --format=FORMAT   Output format: text (default) or json
      --feedback        Include findings with feedback level
      --include-virtual Include virtual pages (paginated, taxonomies) in audit

The 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.

By 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.

Configuration

Customize audit thresholds and enabled checks in your configuration file:

doctor:
  seo:
    title: { min: 30, max: 60 }
    description: { min: 120, max: 160 }
    content: { min_words: 300 }
    checks:
      title: true
      description: true
      canonical: true
      h1: true
      og_tags: true
      img_alt: true
      content_length: true
      lang_attribute: true