What's on this page

Overview
Options
Pages
Data
Static
Assets
Layouts
Output
Cache
Server
Optimize
Override configuration

Configuration

Overview

The website configuration is defined in a YAML file named cecil.yml or config.yml stored at the root:

<mywebsite>
└─ cecil.yml

Cecil offers many configuration options, but its defaults are often sufficient. A new site requires only these settings:

title: "My new Cecil site"
baseurl: https://mywebsite.com/
description: "Site description"

The following documentation covers all supported configuration options in Cecil.

Options

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’s 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

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'

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_EN
  - 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"

metatags

metatags are SEO and social helpers that can be automatically injected in the <head>, with the partial template metatags.html.twig.

Example:

<html lang="{{ site.language }}">
  <head>
    <meta charset="utf-8">
    {{ include('partials/metatags.html.twig') }}
  </head>
  <body>
    ...
  </body>
</html>

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
Favicon links
Previous and next page links
Pagination links (first, previous, next, last)
Canonical URL
Links to alternate versions (i.e.: RSS feed, others languages)
rel=me links
Open Graph
Facebook profile ID
Twitter/X Card
Mastodon meta
Structured data (JSON-LD)

metatags options

Cecil uses page’s front matter to feed meta tags, and fallbacks to site options if 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

If needed, title and image can be overridden:

{{ include('partials/metatags.html.twig', {title: 'Custom title', image: og_image}) }}

metatags configuration

metatags:
  title:                 # title options
    divider: " &middot; "  # string between page title and site title
    only: false            # displays page title only (`false` by default)
    pagination:
      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:
    enabled: true        # includes favicon (`true` by default)
    image: favicon.png     # path to favicon image
    sizes:
      - "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)
  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 is 2 others way to enable the debug mode:

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

Pages

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

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

pages:
  frontmatter: yaml

pages.body

Pages’ 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 (false by default).

pages:
  body:
    highlight: false

pages.body.images

Images handling options.

pages:
  body:
    images:
      formats: []       # adds alternative image formats as `source` (e.g. `[webp, avif]`, empty array by default)
      resize: 0         # resizes all images to <width> (in pixels, `0` to disable)
      responsive: false # adds responsives images them 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: ''   # fill <img> background before loading ('color' or 'lqip', empty by default)
      class: ''         # put default class to each image (empty by default)
      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:

disabled: published: false
excluded from list pages: excluded: true
excluded from localization: multilingual: false

Since version 8.68.0 you can override the default robots.txt page by creating a page with the same path:
pages/robots.md

---
layout: robots
output: txt
---
User-agent: AI-bot
Disallow: /

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

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']

If you use Bootstrap Icons you can exclude the node_modules except node_modules/bootstrap-icons with a regular expression:

exclude: ['sass', 'scss', '*.scss', 'package*.json', '#node_modules/(?!bootstrap-icons)#']

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

Assets

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>

Layouts

Templates options.

layouts.dir

Templates directory source (layouts by default).

layouts:
  dir: layouts

layouts.images

Images handling options.

layouts:
  images:
    formats: []       # used by `html` function: adds alternatives image formats as `source` (empty array by default)
    responsive: false # used by `html` function: adds responsive images (`false` by default)

layouts.translations

Translations handling options.

layouts:
  translations:
    dir: translations       # translations source directory (`translations` by default)
    formats: ['yaml', 'mo'] # translations files format (`yaml` and `mo` by default)

layouts.components

Templates Components options.

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

Output

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’s 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

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.

Override configuration

Environment variables

The configuration can be overridden through environment variables.

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/"

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

Suggest a modification

← Quick Start Templates →

What's on this page

Overview
Options
Pages
Data
Static
Assets
Layouts
Output
Cache
Server
Optimize
Override configuration