What's on this page

Configuration

The website configuration is defined in a YAML file named config.yml by default and stored at the root:

<mywebsite>
└─ config.yml

Example:

title: "Cecil"
baseline: "Your content driven static site generator."
baseurl: https://cecil.local/
language: en

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

date

Date format and timezone.

date:
  format: <format>     # date format (`F j, Y` by default)
  timezone: <timezone> # date timezone (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: <language code> # unique code (`en` by default)

languages

List 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`)

Localize configuration options

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"

taxonomies

List of vocabularies, paired by plural and singular value.

taxonomies:
  <plural>: <singular>

Default taxonomies:

taxonomies:
  categories: category
  tags: tag

pagination

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

pagination:
  max: <int>   # maximum number of entries per page (`5` by default)
  path: <path> # path to the paginated page (`page` by default)

Example:

pagination:
  max: 10
  path: page

Disable pagination

Pagination can be disabled:

pagination:
  enabled: false

menus

A menu is made up of a unique name and entry’s properties.

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

Example:

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

Override entry properties

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

sections' pages path

Defines a custom path for all pages of a Section.

paths:
  - section: <section’s name>
    language: <language> # optional
    path: <path of pages, with palceholders>

Placeholders

:year
:month
:day
:section
:slug

Example:

paths:
  - section: Blog
    path: :section/:year/:month/:day/:slug # e.g.: /blog/2020/12/01/my-post/
  - section: Blog
    language: fr
    path: blogue/:year/:month/:day/:slug # e.g.: /blogue/2020/12/01/mon-billet/

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 meta
Twitter Card
Mastodon meta
Structured data (JSON-LD)

metatags options and front matter

Cecil uses page’s front matter to feed meta tags, and fallbacks to site options if needed.

title: "Page/site title"
description: "Page/site description"
tags: [tag1, tag2]                   # feeds keywords meta
keywords: [keyword1, keyword2]       # obsolete
author: "Author name"
image: image.jpg                     # for OpenGraph and Twitter Card
canonical:                           # to override the generated canonical URL
  url: <URL>
  title: "<URL title>"               # optional
social:
  twitter:
    url: <URL>                       # used for `rel=me` link
    site: username                   # main account
    creator: username                # content author account
  mastodon:
    url: <URL>
    creator: handle
  facebook:
    url: <URL>
    id: 123456789
    firstname: Firstname
    lastname: Lastname
    username: 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)
  image:
    enabled: true        # injects image (`true` by default)
  robots: "index,follow" # web crawlers directives (`index,follow` by default)
  articles: "blog"       # articles' section (`blog` by default)
  jsonld:
    enabled: false       # injects JSON-LD structured data (`false` by default)
  favicon:
    enabled: true        # injects 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

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: Fançais
    locale: fr_FR

Localize configuration options

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"

theme

The theme name or an array of themes name.

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

Examples:

theme: hyde

theme:
  - serviceworker
  - hyde

virtual pages

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

output

Defines where and in what format(s) content is rendered.

dir

Directory where rendered pages’ files are saved.

output:
  dir: <directory> # `_site` by default

formats

List of output formats, in which of them pages’ content is rendered (e.g. HTML, JSON, XML, RSS, Atom, etc.).

output:
  formats:
    - name: <name>            # name of the format, e.g.: `html` (required)
      mediatype: <media type> # media type (MIME), 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 by pagetypeformats (see below) and by the output page’s variable.

pagetypeformats

Array of output formats by 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 same type of page. For example the section page type can be automatically rendred in HTML and Atom.

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]

debug

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

debug: <true|false>

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

When debug is enabled, you can easily dump a variable in your templates using:

{{ dump(variable) }}
# or
{{ d(variable) }} # HTML dump

headers

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

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

Example:

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"

Default configuration

Your site configuration (config.yml) overrides the following default configuration.

pages

Where pages’ files (Markdown or plain text) are stored.

pages:
  dir: pages                                       # pages files directory (`pages` by default, previously `content`)
  ext: [md, markdown, mdown, mkdn, mkd, text, txt] # supported files formats, by extension
  exclude: [vendor, node_modules]                  # directories, paths and files name to exclude (accepts globs, strings and regexes)
  sortby: date                                     # default collections sort method ("date" by default)
  #sortby:
  #  variable: date    # date|updated|title|weight
  #  desc_title: false # false|true
  #  reverse: false    # false|true

frontmatter

Pages’ variables format (YAML by default).

pages:
  frontmatter:
    format: yaml # front matter format: `yaml`, `ini`, `toml` or `json` (`yaml` by default)

body

Pages’ content format and converter’s options.

pages:
  body:
    format: md         # page body format (only `md`, Markdown, is supported)
    toc: [h2, h3]      # headers used to build the table of contents
    highlight:
      enabled: false   # enables code syntax highlighting (`false` by default)
    images:            # how to handle images
      lazy:
        enabled: true  # adds `loading="lazy"` attribute (`true` by default)
      decoding:
        enabled: true  # adds `decoding="async"` attribute (`true` by default)
      resize:
        enabled: false # enables image resizing by using the `width` extra attribute (`false` by default)
      formats: []      # creates and adds formats images as `source` (empty by default)
      responsive:
        enabled: false # creates responsive images and add them to the `srcset` attribute (`false` by default)
      class: ''        # put default class to each image (empty by default)
      caption:
        enabled: false # puts the image in a <figure> element and adds a <figcaption> containing the title (`false` by default)
      remote:
        enabled: true  # enables remote image handling (`true` by default)
        fallback:
          enabled: false # enables a fallback if image is not found (`false` by default)
          path: ''       # path to the fallback image, stored in assets dir (empty by default)
      placeholder: ''  # fill <img> background before loading ('color' or 'lqip', empty by default)
    links:
      embed:
        enabled: false # turns links in embedded content if possible (`false` by default)
        video:
          ext: [mp4, 'webm'] # video files extensions
        audio:
          ext: [mp3]         # audio files extensions
      external:
        blank: false     # if true open external link in new tab
        noopener: true   # add "noopener" to `rel`  attribute
        noreferrer: true # add "noreferrer" to `rel`  attribute
        nofollow: true   # add "nofollow" to `rel`  attribute
    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)

To know how those options impacts your content see Content > Markdown documentation.

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'

default pages

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
      exclude: true
    robots:
      path: robots
      title: Robots.txt
      layout: robots
      output: txt
      published: true
      exclude: true
      multilingual: false
    sitemap:
      path: sitemap
      title: XML sitemap
      layout: sitemap
      output: xml
      changefreq: monthly
      priority: 0.5
      published: true
      exclude: true
      multilingual: false
    atom:
      path: atom
      layout: feed
      output: xsl
      uglyurl: true
      published: true
      exclude: true
    rss:
      path: rss
      layout: feed
      output: xsl
      uglyurl: true
      published: true
      exclude: true

Each one can be:

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

data

Where data files are stored and what extensions are handled.

data:
  dir: data                        # data directory
  ext: [yaml, yml, json, xml, csv] # array of files extensions.
  load: true                       # enables `site.data` collection

Supported formats: YAML, JSON, XML and CSV.

static

Where static files are stored (CSS, images, PDF, etc.).

static:
  dir: static # files directory
  target: ''  # target directory
  exclude: [sass, scss, '*.scss', 'package*.json', 'node_modules'] # list of excluded files (accepts globs, strings and regexes)
  load: false # enables `site.static` collection (`false` by default)

Example:

static:
  dir: docs
  target: docs
  exclude:
    - 'sass'
    - '*.scss'
    - '/\.bck$/'
  load: true

assets

Assets handling options.

assets:
  dir: assets            # assets files directory (`assets` by default)
  target: assets         # where remote and resized assets are saved
  fingerprint:
    enabled: true        # enables fingerprinting (`true` by default)
  compile:
    enabled: true        # enables Sass files compilation (`true` by default)
    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)
  minify:
    enabled: true        # enables CSS et JS minification (`true` by default)
  images:
    resize:
      dir: thumbnails      # where resized images are stored (`thumbnails` by default)
    optimize:
      enabled: false       # enables images optimization with JpegOptim, Optipng, Pngquant 2, SVGO 1, Gifsicle, cwebp, avifenc (`false` by default)
    quality: 75            # image quality after optimization or resize (`75` by default)
    responsive:
      widths: []           # `srcset` widths (`[480, 640, 768, 1024, 1366, 1600, 1920]` by default)
      sizes:
        default: '100vw'   # default `sizes` attribute (`100vw` by default)
      enabled: false       # used by `html` filter: creates responsive images by default (`false` by default)
    formats: []            # used by `html` filter: creates and adds formats images as `source` (empty by default)

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

layouts

Where templates and translations files are stored.

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

themes

Where themes are stored.

themes:
  dir: themes # themes directory

cache

Cache options.

cache:
  enabled: true         # enables cache support (`true` by default)
  dir: '.cache'         # cache files directory (`.cache` by default)
  templates:
    enabled: true       # enables cache for Twig templates
    dir: templates      # templates files cache directory (`templates` by default)
  assets:
    dir: 'assets'       # assets files cache directory (`assets` by default)
    remote:
      dir: remote       # remote files cache directory (`remote` by default)
  translations:
    enabled: true       # enables cache for translations dictionary
    dir: 'translations' # translations files cache directory (`assets` by default)

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

Suggest a modification

← Templates Commands →

What's on this page

Options
Default configuration
Override configuration