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:

format: PHP date format specifier
timezone: date 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
- style: output formatter’s name (see documentation of scssphp)
- import: array of imported path
- variables: array of preset variables (see documentation of scssphp)
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