Slugification improvements

• Updated the Page::slugify method to detect Chinese (Han) characters in the input and apply the Chinese ruleset for slugification when appropriate, improving URL generation for Chinese content.
• Refactored the Url class to delegate slugification to Page::slugify, removing its own slugifier instance and related logic for consistency and code reuse.

Image processing API refactor and simplification

• The cover method for cropping images to specific dimensions has been removed from both the Asset class and the Twig filters. All resizing and cropping operations are now handled via an enhanced resize method that accepts both width and height, and crops the image if both are provided.
• The resize method in Asset and the corresponding Twig filter now accept both width and height as optional parameters, providing greater flexibility and reducing code duplication.
• The Image::resize method is updated to handle both resizing and cropping, replacing both the previous resize and cover methods. It now also includes an option to remove animation from images.

Template and filter usage updates

• The cover Twig filter is removed, and all usages in templates are updated to use the new resize(width, height) signature.
• The metatags template now uses the new resize filter for OpenGraph images, passing both width and height where appropriate.

Error handling and code clarity

• Exception messages throughout the image processing code have been standardized to include periods at the end and clarify the error context.
• Minor code cleanups and improved documentation for image processing methods.

HTML image rendering improvements

• The sizes attribute for <source> elements is now only included when not empty, preventing invalid HTML.
• The srcset attribute is only added to images when it is not empty, improving output correctness.

Overall, these changes modernize and streamline image handling, making the API easier to use and maintain.

PHP Version and Dependency Upgrades

The minimum required PHP version is now 8.2 (was 8.1), and support for PHP 8.1 is dropped across all configuration and documentation files, including composer.json, CI/CD workflows, and documentation.
Symfony and related PHP package dependencies are updated from version 6.4 to 7.4, and other dependencies are also upgraded. New dependency jolicode/jolinotif is added, and performing/twig-components is bumped to ^0.7.

Documentation Updates

All documentation, including the README and quick start guides, is updated to require PHP 8.2+.
The build instructions now include steps for building both PHAR and full packages, and reference the new tools used.

Feature Additions

Adds a --notif option to CLI commands, enabling desktop notifications on build completion and server start.

Asset Metadata and API Enhancements

• Audio and video assets now expose richer metadata: audio assets provide duration, bitrate, and channel, while video assets provide duration, width, and height. These properties are now directly available on asset objects, making them easier to use in templates.

Documentation Updates

• The documentation for templates and asset usage is updated to reflect new asset properties and usage examples for audio and video files.

These changes collectively make asset handling more powerful and easier to use, especially for media files, while improving code clarity and maintainability.

Major new features

• Improved support for responsive images — Added support for pixel density (DPR) for responsive images (allows optimization of srcset for high-density screens).
• Ability to override robots.txt — Ability to create a pages/robots.md page to replace the default robots.txt. Useful for managing indexing exclusions per project.
• Improved post-processing — Continued use of extension/post-processor capabilities (inherited from the 8.x branch) to enable final output processing.

Improvements & usability

• Simplified configuration structure — Options are easier to disable (option: false or option: enabled: false); automatic import of theme configurations via setConfig() / setSourceDir().
• Redesigned/enhanced cache — New, more robust cache mechanism (automatic rebuilding when files change), at the cost of a slight performance hit in some cases.
• Improved error message handling and display — Error messages are clearer to facilitate debugging.

Major fixes

• Updated remote asset management — Remote assets are better managed (caching, fallback, etc.).
• Fixes for templates and filters — Cleanup of deprecated elements/those left in the documentation (following the 8.0 → 8.x migration) and various fixes related to asset/template rendering.

Breaking changes & points of attention

• Removal of default taxonomies — tag and category are no longer created automatically: if you were using these taxonomies, you must declare them explicitly in the taxonomies: configuration. There is a risk of broken pages if you update without adapting the configuration.
• Renaming/moving options — Several options have been renamed or moved (e.g., pagination → pages:pagination, paths → pages:paths, remote_fallback → fallback, force_slash → leading_slash).
• Check custom templates — Some deprecated Twig files and filters were removed in the 8.x updates; you should review and update your custom templates.

Recommended actions for migration

1. Explicitly add taxonomies: if you plan to use tags/category.
2. Check and adapt the renamed options (pagination, paths, assets fallback, leading_slash).
3. Test the complete build and verify the cache/remote assets.
4. Review the Twig templates (deprecated functions/filters) and take advantage of new features (DPR/pixel density in images).

1. simplification of the configuration structure
2. cache enhancement: a little bit less performant but more comfortable
3. better errors message management

Enhancements

Configuration

• An option can be disabled directly with option:false or with the subkey enabled: option:enabled:false
• Themes configuration is automatticaly imported on setConfig() and setSourceDir()
• Deprecated options are now listed in the dedicated file config/deprecated.php

Cache and assets

• Cache mecachics rebuilded: it's a little bit less performant but it better handle files changed to refresh cache automatically
• Remote files are now cached 7 days

Breaking changes

• Default taxonomies tag and category removed. If you used them, you must add each one to your site configuration
• Configuration options moved:
  • pagination -> pages:pagination
  • paths -> pages:paths
• Assets options renamed:
  • remote_fallback -> fallback
  • force_slash -> leading_slash

• Extends Cecil with output post processors
• Customized Generator, Postprocessor and Extension class available for themes too
• Better configuration options hierarchy
• Access to raw site configuration from a template with config.xxx
• Configuration validation enhanced
• Logs enhanced
• Asset find file enhanced

Breaking changes

• Dropping support for PHP 7.x
• No more legacy support of the content directory: use pages instead

Configuration options

frontmatter:
body:
defaultpages:
virtualpages:
generators:
translations:
extensions:
postprocess:

have been changed for:

pages:
  frontmatter:
  body:
  default:
  virtual:
  generators:
layouts:
  translations:
  extensions:
optimize:

Commands

• The build and serve command option --postprocess have been changed for --optimize

Templates

• pagination.html.twig removed (use paginator.html.twig instead)
• googleanalytics.js.twig removed
• All deprecated functions and filters have been removed

Fix

• Fix render default timezone
• Fix localizeddate fallback filter
• Fix asset() bundle
• Fix HTML asset filter with WebP
• Fix remote asset fallback

Performance

• Collection item access time enhanced
• post processors class autoloader moved
• jsonld.js.twig performances fixed

Docs

• Documentation updated

Miscs

• Dependencies updated

Tests

• Test fixtures enhanced

Get dimensions of a video asset

{% set asset = asset('video.mp4') %}
Dimensions: {{ asset.video.width }} x {{ asset.video.height }}

Documentation →

Miscs

• Dependencies updated

Disable default metatag image

You can now disable the metatag image (Open Graph and co) with the following option:

```yaml
metatags:
  image:
    enabled: false

Documentation →

Miscs

• Dependencies updated

New dump function

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

Documentation →

Miscs

• Dependencies updated
• Skeleton templates updates

i18n for taxonomy

Adds i18n support to the taxonomy feature: you can use localized vocabularies and terms in your pages.

Configuration

taxonomies:
  categories: categorie
languages:
  - code: en
    name: English
    locale: en
  - code: fr
    name: Français
    locale: fr_FR
    config:
      taxonomies:
        catégories: catégorie

Page

example.fr.md:

---
catégories: [Catégorie 1, Catégorie 2]
---

Template

vocabulary.html.twig:

<ul>
{% for term in page.terms %}
  <li>
-    <h2><a href="{{ url(page.path ~ '/' ~ term.id) }}">{{ term.name }}</a> ({{ term|length }})</h2>
+    <h2><a href="{{ url(term.id, {language: site.language}) }}">{{ term.name }}</a> ({{ term|length }})</h2>
  </li>
{% endfor %}
</ul>

Documentation →

Fix

• Do not remove the sectionvariable of excluded pages
• Fix live reload script injection
• Fix show:content command

Miscs

• Dependencies updated
• show:config command enhanced

Processing time and consumed memory

Display the processing time and consumed memory on each step, in verbose mode (-vv):

(...)
<step name> done in X.XX s (X mb)
(...)

Miscs

• Code enhanced
• Dependencies updated

Changes ID of localized pages

The way to define a page ID have been refactored: the language code of a translated page is no more a suffix (page.code) and is now a prefix (code/page).

Example: blog/post-1.fr become fr/blog/post-1.

Fix

• getIdWithoutLang() fixed
• Pagination sorting fixed

Miscs

• native_function_invocation rule applied for better performance (e.g.: \is_array() instead of is_array())
• Dependencies updated

New variable page.paginator.links.path

The paginator variable page.paginator.links.path returns the Page ID without position index.

Example:

{% if page.paginator %}
<div>
  {% for paginator_index in 1..page.paginator.count %}
    {# not the current page: URL #}
    {% if paginator_index != page.paginator.current %}
      {# the first page #}
      {% 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 %}
    {# the current page: not URL #}
    {% else %}
  {{ paginator_index }}
    {% endif %}
  {% endfor %}
</div>
{% endif %}

Documentation →

Fix

• Fix metatags favicon asset
• Fix clear-cache command option
• Fix console debug mode
• Fix logo in JSON-LD template
• Fix JSON templates
• <script> tag added to live reload script (by @ahnlak)

Miscs

• Dependencies updated
• Use Composer dump-autoloaderdirective for better performance
• Step logged messages enhanced

New taxonomy template lookup rule

You can now easily create a custom template to list pages of a specific taxonomy term (singular): taxonomy/<singular>.<format>.twig (Request #1669).

Documentation →

Fix

• Fix favicons generation
• Fix html filter in case of class attribute if empty

Docs

• Documentation globally enhanced

Miscs

• Dependencies updated
• Code coverage: add tests for image asset handling

New asset filter and functions for images

Convert an image to the WebP format:

{{ asset|webp }}

Documentation →

Build srcset attribute from an asset and retrieve available sizes for a given class name:

{{ image_srcset(asset) }}
{{ image_sizes('class') }}

Documentation →

Example:

{% set photo = asset('photo.jpg') %}
<picture>
  <source type="image/webp" srcset="{{ image_srcset(photo|webp) }}" sizes="{{ image_sizes('photo') }}">
  <img src="{{ url(photo) }}" width="{{ photo.width }}" height="{{ photo.height }}" alt="" class="photo" srcset="{{ image_srcset(photo) }}" sizes="{{ image_sizes('photo') }}">
</picture>

Fix

• Disable dataurl filter for SVG

LQIP filter

The Twig filter lqip returns a Low Quality Image Placeholder (LQIP) as data URL.

{{ asset(image_path)|lqip }}

Documentation →

Example:

{% set photo_full = asset('/photo.jpeg') %}
{% set photo = photo_full|resize(640) %}
<div style="background-image:url({{ photo|lqip }});background-repeat:no-repeat;background-position:center;background-size:cover;">
  <a href="{{ url(photo_full) }}">{{ photo|html }}</a>
</div>

Example of progressive loading of images gallery:

Docs

• imgix CDN configuration added

Miscs

• Dependencies updated
• Better image handling

Support of image CDN

You can easily use a CDN to provide the images of your site, for example:

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

CDN providers →

Documentation →

Fix

• Fix link to Markdown file, with anchor
• Fix duplicated responsive image

Docs

• Commands list updated
• Images documentation enhanced

Miscs

• Assets and WebP converter code refactored
• Add auto-refresh to 404 locally served page
• Better responsive widths

decoding="async" added to images

The attribute decoding="async" is automatically added to Markdown images.

Example:

![](/image.jpg)

Is converted to:

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

Documentation →

Fix

• Fix default class in Markdown images
• Fix configuration error messages

Docs

• Update metatags configuration

Miscs

• Dependencies updated
• Code coverage enhanced
• Print a message if the EXIF extension is loaded
• exif_read_data error handler refactored

EXIF and audio data

EXIF and audio data are available for static files and asset.

EXIF Example:

# photo's date in seconds
{{ asset('photo.jpeg').exif.DateTimeOriginal|date('U') }}

Fix

• Fix cache tag for image quality
• Fix default layout page CSS
• Fix url(page) default output format

Miscs

• Dependencies updated

Add base page URL to TOC anchor

Example:

{{ page.body|toc('html', 'https://example.com/page/') }}
{{ page.body|toc(url=url(page)) }}

Documentation →

Fix

• Fix sort_by_date filter
• Fix default page layout
• Fix Markdown image title
• Fix path in case of only one page is loaded

Docs

• Remove Forestry references (because Forestry is dead)
• Update Deploy
• Update templates

Miscs

• Dependencies updated

JSON Feed output format

Add support of JSON Feed as output format.

output:
  pagetypeformats:
    section: ['html', 'atom', 'jsonfeed']

Documentation →

Fix

• Enforcing runtime checks for required PHP extensions (by @benjaminhirsch)
• Fix pages filter and map in render step

Miscs

• Code enhanced
• Dependencies updated
• symfony/polyfill-intl-icu added

• Feeds links available from pages in a section
• Cecil is now available through Homebrew

Fix

• Fix French translation
• Fix remote asset files handling
• Handling of video files by the local server
• Fix homepage generator if no other pages

Docs

• Minor updates

Miscs

• Feeds XSL refactored
• Better local server 404 page
• Dependencies updated

Remove cache files by regular expression

Example:

php cecil.phar serve --clear-cache="\.css"

Removes cached CSS files and preserves the rest of the cache.

Documentation →

Fix

• Pattern used in cache prune method
• Should not convert a line link in block
• Fix favicon sizes attribute
• Minor fix on Markdown convertor

Docs

• Content page updated

Miscs

• Code commented

Custom responsive image sizes

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

The sizes attribute take the value of the assets.images.responsive.sizes.default configuration option by default, and can be customized by creating a new entry named with the class name added to the image.

Example:

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

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

Documentation →

Fix

• Normalize page path to build

Create caption for images and embed links having a title

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>

Documentation →

Turn a link into a video or audio element

[The video](/video/test.mp4){controls poster=/images/video-test.png style="width:100%;"}

<video src="/video/test.mp4" controls poster="/images/video-test.png" style="width:100%;"></video>

Documentation →

Fix

• Converts page even it contain a wrong language code

Miscs

• Dependencies updated

New option to add default class to body images

body:
  images:
    class: '' # put default class to each image (empty by default)

Documentation →

Fix

• Fix Twitter account in metatags template
• Fix embedded links disable option
• Apply custom path before the convert step (create)

Docs

• Content page updated

Miscs

• Code cleaned

New canonical variable to override the generated canonical URL

If the partial metatags.html.twig is included in your main template, a canonical URL is automatically added to the page <head>.
With the canonical variable (set in page front matter) you can override the canonical URL and the canonical title:

canonical:
  url: <URL>
  title: "<URL title>" # optional

Documentation →

Local fallback for remote images

You can specify a – generic – fallback image in case of remote images are not available.

body:
  images:
    remote:
      enabled: true
      fallback:
        enabled: true # enables a fallback if remote image is not found (false by default)
        path: 'images/no-image.png' # path to the fallback image, stored in `assets` dir (empty by default)

Documentation →

Support of embed GitHub Gist link

GitHub Gist can be easly embed by adding the {embed} attribute.

[Cecil build script](https://gist.github.com/ArnaudLigny/6b2aa9e6b25581c96435e9296efe0c0e){embed}