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: <bool> # false by default

description

Site description (~ 250 characters).

description: "<description>"

date

Date format and timezone.

date:
  format: <format>     # date format (`j F Y` by default)
  timezone: <timezone> # date timezone (`Europe/Paris` by default)

format: PHP date format specifier
timezone: see timezones

Example:

date:
  format: 'Y-m-d'
  timezone: 'UTC'

taxonomies

List of vocabularies, paired by plural and singular value.

taxonomies:
  <plural>: <singular>

Default taxonomies:

taxonomies:
  categories: category
  tags: tag

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: <int>   # integer value used to sort entries (lighter first)

By default a main menu is created and contains the home page and sections entries.

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

metatags

metatags are SEO helpers that can be injected automatically in the <head> by including the partials/metatags.html.twig template.

Example:

<html lang="{{ site.language }}">
  <head>
    <meta charset="utf-8">
    {%~ include 'partials/metatags.html.twig' ~%}
    [... other head elements ...]
  </head>
  [...]
</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)
Open Graph
Twitter Card
Structured data (JSON-LD)

metatags options and front matter

Cecil uses page’s front matter to feed meta tags, and fallbacks to the site configuration 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 # used by OpenGraph and Twitter Card
canonical: # used to override the generated canonical URL
  url: <URL>
  title: "<URL title>" # optional
social:
  twitter:
    site: username
    creator: username
  facebook:
    id: 123456789
    firstname: Firstname
    lastname: Lastname
    username: username

If needed title and image can be overridden:

{% include 'partials/metatags.html.twig' with {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: <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"

theme

The theme name or an array of themes name.

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

Examples:

theme: hyde

theme:
  - serviceworker
  - hyde

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

googleanalytics

Google Analytics user identifier:

googleanalytics: UA-XXXXX

The Universal Analytics ID is used by the built-in partial template googleanalytics.html.twig.

virtualpages

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:

virtualpages:
  - 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]` (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]

paths

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/

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

Default configuration

The website configuration (config.yml) overrides the default configuration.

defaultpages

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

index.html (home page)
404.html
robots.txt
sitemaps.xml
atom.xsl
rss.xsl

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

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)

frontmatter

Pages’ variables format (YAML by default).

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

body

Pages’ content format and converter’s options.

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)
    webp:
      enabled: false  # adds a WebP image as a `source` (`false` 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)
  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
  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.

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

layouts

Where templates files are stored.

layouts:
  dir: layouts # layouts directory

themes

Where themes are stored.

themes:
  dir: themes # themes directory

translations

Where and in what format translations files are stored.

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

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 (`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     # `html` filter: creates responsive images (`false` by default)
    webp:
      enabled: false     # `html` filter: creates and adds a WebP image as a `source` (`false` by default)

Image CDN

If the option assets.images.cdn is enabled then URL of assets will be replaced by the provided CDN url.

assets:
  images:
    cdn:
      enabled: false  # enables Image CDN (`false` by default)
      canonical: true # is `image_url` must be canonical or not (`true` by default)
      remote: true    # includes remote images (`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 asset path or the URL of the remote image
%width% replaced by the image width
%quality% replaced by the assets.images.quality option
%format% replaced by the image format

CDN provider examples

Cloudinary

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

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

TwicPics

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

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.

postprocess

Options of files optimizations after build step (post process).

postprocess:
  enabled: false     # enables (`false` by default)
  html:
    ext: [html, htm] # list of files extensions
    enabled: true    # enables HTML post processing
  css:
    ext: [css]       # list of files extensions
    enabled: true    # enables CSS post processing
  js:
    ext: [js]        # list of files extensions
    enabled: true    # enables JS post processing
  images:
    ext: [jpeg, jpg, png, gif, webp, svg] # list of files extensions
    enabled: true                         # enables images post processing

Images compressor will use these binaries if they are present in the system: JpegOptim, Optipng, Pngquant 2, SVGO, Gifsicle and cwebp.

cache

Cache options.

cache:
  dir: '.cache' # cache directory
  enabled: true # enables cache
  templates:    # Twig templates cache
    dir: templates # templates cache directory
    enabled: true  # enables templates cache
  assets:       # assets cache
    dir: 'assets/remote' # the subdirectory of remote assets cache
  translations:
    dir: 'translations' # translations cache directory
    enabled: true       # enables translations cache

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:

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'

Custom generator

It is possible to create a custom Generator, just add it to the list above, and create a new class in the Cecil\Generator namespace.

Example:

/generators/Cecil/Generator/MyGenerator.php

<?php
namespace Cecil\Generator;

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

class MyGenerator 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)
          ->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);
    }
}

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