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

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"

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

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

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>

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`

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

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