Cecil logo

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

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)

A default 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

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 an 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.

metatags

Meta tags (for SEO) can be injected automatically in the <head> by including the partials/metatags.html.twig template.

Cecil uses data from page's front matter to feed meta tags and from config: 

title: 'Site / Page title'
description: 'Site / Page description'
keywords: ['keyword1', 'keyword2'] # Use `tags` in case of a Page
author: 'Author name'
image: 'image.jpg'
social:
  twitter:
    site: '@username'
    creator: '@username'
  facebook:
    id: '123456789'
    firstname: 'Firstname'
    lastname: 'Lastname'
    username: 'username'

Cecil search for a favicon.png file at root of static directory.

Default configuration: 

metatags:
  title:
    divider: ' &middot; ' # String between page title and site title
    only: false           # Display page title only
    pagination:
      shownumber: true    # Display page number in title
      label: 'Page %s'    # How to display page number
  robots: 'index,follow'  # Web crawlers directives
  articles: 'blog'        # Articles' section
  jsonld:
    enabled: true         # Inject JSON-LD meta tags

googleanalytics

Google Analytics user identifier: 

googleanalytics: "UA-XXXXX"

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

Defines where and how files are generated.

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: don’t apply this format to pages identified by 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

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

Define a custom path for all pages of a Section.

Example: 

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

Available placeholders

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

debug

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

Example: 

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 local website configuration file (config.yml) overrides the default configuration.

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

Where content files are stored.

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

Supported format: Markdown and plain text files.

frontmatter

Pages’ variables format.

  • format: front matter format (yaml by default)

body

Pages’ content format.

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

data

Where data files are stored.

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

Supported format: YAML, JSON, XML and CSV.

static

Where static files and assets (CSS, images, PDF, etc.) are stored.

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

Example: 

static:
  dir: docs
  target: docs
  exclude:
    - 'sass'
    - '*.scss'
    - '/\.bck$/'
  load: true

layouts

Where templates files are stored.

  • dir: layouts directory (layouts by default)

themes

Where themes are stored.

  • dir: themes directory (themes by default)

assets

Assets handling options. 

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

postprocess

Files optimizations (post process) options. 

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

Cache options.

  • dir: cache directory (.cache by default)
  • enabled: boolean (false by default)
  • templates: Twig cache
    • dir: the subdirectory of .cache where templates cache is stored (default: templates)
    • enabled: true or false (default: true)
  • assets: assets cache
    • dir: the subdirectory of remote assets cache

generators

Generators priorities. 

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'

Config file alternative

Environment variables

Configuration can be defined through environment variables.

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

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

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

Suggest a modification

← Templates Commands →