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 identifiername
: name used in templatesurl
: relative or absolute URLweight
: 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
inpath/amp/index.html
)suffix
: file name (ie:/index
inpath/index.html
)extension
: file extension (ie:html
inpath/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 codename
: human readable name of the languagelocale
: 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 extensionsload
: 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 filesload
: boolean (false
by default, used bysite.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 filenamecompile
: 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 atext/css
ortext/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)templates
: Twig cache-
dir
: a subdirectory of.cache
where templates cache is stored (default:templates
) -
enabled
:true
orfalse
(default:true
)
-
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.