Cecil logo

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)

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

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

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:

  1. Run a command with the -vvv option
  2. 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:

  1. disabled: published: false
  2. excluded from list pages: exclude: true
  3. 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