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

baseline

Short description (~ 20 characters).

baseline: "<baseline>"

baseurl

The base URL.

baseurl: <baseurl>

Example:

baseurl: http://localhost:8000/

canonicalurl

If set to true the url() function will return the absolute URL (false by default).

canonicalurl: false

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 used in templates
      url: <url>      # relative or absolute URL
      weight: <XX>    # 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
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: en # `en` by default

languages

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

languages:
  - code: <code>     # language unique code
    name: <name>     # human readable name of the language
    locale: <locale> # locale code of the language

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>

The first theme overrides the others, and so on.

Examples:

theme: hyde
theme:
  - serviceworker
  - hyde

pagination

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

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

Example:

pagination:
  max: 5
  path: "p"

Disable pagination

Pagination can be disabled:

pagination:
  enabled: false

googleanalytics

Google Analytics user identifier:

googleanalytics: UA-XXXXX

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 front matter variables.

Example:

virtualpages:
  - path: code
    redirect: https://github.com/ArnaudLigny

output

Defines where and how files are generated.

dir

Directory where rendered pages’ files are saved.

output:
  dir: _site # `_site` by default

formats

List of output formats.

output:
  formats:
    <name>:
      name: <name>            # name of the format (e.g.: `html`)
      mediatype: <media type> # media type (MIME). ie: 'text/html'
      subpath: <sub path>     # sub path (e.g.: `/amp` in `path/amp/index.html`)
      suffix: <suffix>        # file name (e.g.: `/index` in `path/index.html`)
      extension: <extension>  # file extension (e.g.: `html` in `path/index.html`)
      exclude: [<variable>]   # don’t apply this format to pages identified by listed variables (e.g.: `[redirect]`)

pagetypeformats

Array of generated output formats for each page type (homepage, page, section, vocabulary and term).

output:
  pagetypeformats:
    page: [<format>]
    homepage: [<format>]
    section: [<format>]
    vocabulary: [<format>]
    term: [<format>]

Example:

output:
  dir: _site
  formats:
    - name: html
      mediatype: text/html
      suffix: index
      extension: html
    - name: rss
      mediatype: application/rss+xml
      suffix: rss
      extension: xml
      exclude: [redirect, paginated]
  pagetypeformats:
    page: [html]
    homepage: [html, rss]
    section: [html, rss]
    vocabulary: [html]
    term: [html, rss]

paths

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

debug

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

debug: true

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

Each one can be:

  1. disabled: published: false
  2. excluded from list pages: exclude: true
  3. excluded from localization: multilingual: false

content

Where content files are stored and loaded file extensions (Markdown and plain text files).

content:
  dir: content                                     # pages directory
  ext: [md, markdown, mdown, mkdn, mkd, text, txt] # array of files extensions.

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
  images:                # how to handle images
    lazy:
      enabled: true      # enables lazy loading (`true` by default)
    caption:
      enabled: true      # adds <figcaption> to images with a title (`false` by default)
    remote:
      enabled: true      # enables remote image handling (`true` by default)
    resize:
      enabled: false     # enables image resizing by using the `width` extra attribute (`false` by default)
    responsive:
      enabled: false     # creates responsive images (`false` by default)
    webp:
      enabled: false     # creates WebP images (`false` by default)
  notes:
    enabled: false       # enables Notes blocks (`false` by default)

To know how those options impacts your content see Content > Page > Body 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
    enabled: true
  assets:       # Assets cache
    dir: 'assets/remote' # the subdirectory of remote assets cache

generators

Generators creates pages automictically (sitemap, feed, pagination, etc.) in a definite 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'

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