Configuration

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

<mywebsite>
└─ config.yml

Example:

title: "Cecil"
baseline: "Your content driven static site generator."
baseurl: https://cecil.local/
description: "Cecil is a CLI application that merges plain text files (written in Markdown), images and Twig templates to generate a static website."

Variables

title

Main title of the site.

baseline

Short description (~ 20 characters).

baseurl

The base URL. Must end with a trailing slash (/).

Example:

baseurl: http://localhost:8000/

canonicalurl

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

description

Site description (~ 250 characters).

taxonomies

List of vocabularies, paired by plural and singular value.

Example:

taxonomies:
  categories: category
  tags: tag

A vocabulary can be disabled with the special value disabled:

taxonomies:
  tags: disabled

menus

Each menu entry should have the following properties:

  • id: unique identifier
  • name: name used in templates
  • url: relative or absolute URL
  • weight: used to sort entries (lighter first)

Example:

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

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

Overrides entry properties

A page menu entry can be overridden: use the page index id.

Example:

menus:
  main:
    - id: index
      name: "My amazing homepage!"
      weight: 1

Disable entry

A menu entry can be disabled with enabled: false.

Example:

menus:
  main:
    - id: about
      enabled: false

pagination

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

  • max: number of pages by paginated page (5 by default)
  • path: path to paginated page (page by default)

Example:

pagination:
  max: 10
  path: "page"

Disable pagination

Pagination can be disabled with enabled: false.

Example:

pagination:
  enabled: false

date

Date format and timezone:

Example:

date:
  format: "j F Y"
  timezone: "Europe/Paris"

theme

The theme name (sub-directory of themes) or an array of themes.

Example:

theme:
  - serviceworker
  - hyde

See officials themes.

googleanalytics

Google Analytics user identifier:

googleanalytics: "UA-XXXXX"

Used by the built-in 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/Narno

output

dir

Directory where rendered pages' files are saved (_site by default).

formats

List of output formats.

  • name: name of the format (ie: html)
  • mediatype: media type (formerly known as MIME type)
  • subpath: sub path (ie: /amp in path/amp/index.html)
  • suffix: file name (ie: /index in path/index.html)
  • extension: file extension (ie: html in path/index.html)
  • exclude: excludes pages with specific variables, as array (ie: [redirect])

pagetypeformats

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

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]

language

Site main language (en by default).

languages

Experimental

List of available languages, used by internationalization features.

Required keys:

  • code: language unique code
  • name: human readable name of the language
  • locale: locale code of the language

Localized configuration variables must be stored under the config key.

Example:

languages:
  - code: en
    name: English
    locale: en_US
  - code: fr
    name: Français
    locale: fr_FR
    config:
      title: 'Cecil en français'

paths

Experimental

Custom pages' path (in a section).

Example:

paths:
  - section: Blog
    path: :section/:year/:month/:day/:slug

Available placeholders:

  • :year
  • :month
  • :day
  • :section
  • :slug

Default values

The local website configuration file (config.yml) overrides the Cecil default configuration (default.php).

defaultpages

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

  • robots.txt
  • sitemaps.xml
  • 404.html

The structure is almost identical of virtualpages, except the key:

defaultpages:
  robots:
    path: robots
    title: 'Robots.txt'
    layout: 'robots'
    output: 'txt'
    published: true
  sitemap:
    path: sitemap
    title: 'XML sitemap'
    layout: 'sitemap'
    output: 'xml'
    changefreq: 'monthly'
    priority: '0.5'
    published: true
  404:
    path: '404'
    title:  'Page not found'
    layout:  '404'
    uglyurl:  true
    published:  true

Each one can be disabled with published: false.

content

  • dir: content pages directory (content by default)
  • ext: array of files extensions

Supported format: Markdown and plain text files.

frontmatter

  • format: front matter format (yaml by default)

body

  • format: page body format (md, for Markdown, by default)

data

  • dir: content data directory (data by default)
  • ext: array of files extensions
  • load: boolean (true by default)

Supported format: YAML, JSON, XML and CSV.

static

  • dir: static files directory (static by default)
  • target: target directory (empty by default)
  • exclude: list of excluded files
  • load: boolean (false by default, used by site.static)

exclude accepts globs, strings and regexes.

Example:

static:
  dir: docs
  target: docs
  exclude:
    - '*.pdf'
    - '/\.php$/'
  load: true

layouts

  • dir: layouts directory (layouts by default)

themes

  • dir: themes directory (themes by default)

assets

assets:
  fingerprint:
    enabled: true
  compile:
    enabled: true
    style: nested
    import: [sass, scss]
  minify:
    enabled: true
  • fingerprint: Adds the file fingerprint in the filename (ie: style.c9a87d1be1c3cf7c3837c968b28364ec.min.css)
  • compile: Compiles a SCSS with the given
  • minify: Compresses file content (Available for file with a text/css or text/javascript MIME Type)

postprocess

Experimental

postprocess:
  enabled: false
  html:
    ext: [html, htm]
  css:
    ext: [css]
  js:
    ext: [js]
  images:
    ext: [jpeg, jpg, png, gif, webp, svg]

Images compressor will use these binaries if they are present on your system:

cache

  • dir: cache directory (.cache by default)
  • enabled: boolean (false by default)

generators

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'

Environment variables

Configuration can be defined through environment variables.

For example, the following command will set the website’s baseurl:

export CECIL_BASEURL="https://example.com/"

Name must be prefixed with CECIL_ and the configuration key must be set in uppercase.

Suggest a modification

Templates Commands

Table of contents