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

Variables

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 to your site:

Page title with site title or site title with site baseline
Page description or site description
Page tags or site keywords
Page author or site author
Search engine crawler directives
Favicon links
Previous and next page links
Pagination links (first, previous, next, last)
Canonical URL
Links to alternates formats (e.g.: RSS feed)
Open Graph
Twitter Card
JSON-LD site and article metadata

metatags keys

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

title: "Page or site title"
description: "Page or site description"
keywords: [keyword1, keyword2] # use `tags` key in page front matter
author: "Author name"
image: image.jpg # used by OpenGraph and Twitter Card
social:
  twitter:
    site: username
    creator: username
  facebook:
    id: 123456789
    firstname: Firstname
    lastname: Lastname
    username: username

Tip: If needed the title can be overridden:

{% include 'partials/metatags.html.twig' with {title: 'Custom title'} %}

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)
  articles: "blog"        # articles' section (`blog` by default)
  jsonld:
    enabled: true         # injects JSON-LD meta tags (`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]                  # Adnroid
      - "apple-touch-icon": [120, 152, 180]     # iOS

language

Main language, defined by its code.

language: <language code> # ISO 639-1 code (`en` by default)

languages

List of available languages, used for content and templates localization.

languages:
  - code: <code>     # unique code (ISO 639-1)
    name: <name>     # human readable name
    locale: <locale> # locale code (`language_COUNTRY`, e.g. `en_US`)

Localize configuration variables

To localize configuration variables you must store them under the config key.

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

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 values

The configuration website (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

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: xslt
    uglyurl: true
    published: true
    exclude: true
  rss:
    path: rss
    layout: feed
    output: xslt
    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: content                                     # pages directory
  ext: [md, markdown, mdown, mkdn, mkd, text, txt] # array of pages files extensions
  exclude: [vendor, node_modules]                  # array of 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` by default)

body

Pages’ content format and converter’s options.

body:
  format: md         # page body format (only 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)
    resize:
      enabled: false # enables image resizing by using the `width` extra attribute (`false` by default)
    responsive:
      enabled: false # creates responsive images and add them to the `srcset` attribute (`false` by default)
    webp:
      enabled: false # adds a WebP image as a `source` (`false` by default)
    caption:
      enabled: true  # 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)
  notes:
    enabled: false   # turns remote images to Asset to handling them (`true` by default)

To know how those options impacts your content see Content > Page > 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

assets

Assets handling options.

assets:
  dir: assets            # files directory
  fingerprint:
    enabled: true        # enables fingerprinting (`true` by default)
  compile:
    enabled: true        # enables Sass asset compilation (`true` by default)
    style: expanded      # style of compilation (`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 asset minification (`true` by default)
  target: assets         # where remote and resized assets are saved
  images:
    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:
      enabled: false     # creates responsive images with `html` filter (`false` by default)
      widths: [480, 640, 768, 1024, 1366, 1600, 1920] # `srcset` widths (`[480, 640, 768, 1024, 1366, 1600, 1920]` by default)
      sizes:
        default: '100vw' # `sizes` attribute (`100vw` by default)
    webp:
      enabled: false     # creates a WebP version of images with `html` filter (`false` by default)

Notes:

See documentation of scssphp for details about style compilation and variables
minify is available for file with a text/css or text/javascript MIME Type)
Enables sourcemap output requires debug mode is enabled

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

generators

Generators are used by Cecil to create new pages (e.g.: sitemap, feed, pagination, etc.) from existing pages or from other sources, like configuration file or external sources.

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 add a new 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'))
          ->setPath('mypage')
          ->setType(Type::PAGE)
          ->setLanguage('en')
          ->setTitle('My page')
          ->setBodyHtml('<p>My page body</p>')
          ->setVariable('date', now())
          ->setVariable('menu', [
            'main' => ['weight' => 99],
          ]);

        $this->generatedPages->add($page);
    }
}

Alternative to config file

Environment variables

The configuration can be defined 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

Table of contents