What's on this page
Pages
These options control how pages are loaded, sorted, paginated, routed and generated.
pages.dir
Source directory of pages (pages by default).
pages:
dir: pages
pages.ext
Extensions of pages files.
pages:
ext: [md, markdown, mdown, mkdn, mkd, text, txt]
pages.exclude
Directories, paths and files name to exclude (accepts globs, strings and regexes).
pages:
exclude: ['vendor', 'node_modules', '*.scss', '/\.bck$/']
pages.prefix.separator
List of characters used as separator between a filename prefix (date or weight) and the slug.
pages:
prefix:
separator: ['-', '_']
pages.sortby
Default collections sort method.
pages:
sortby: date # `date`, `updated`, `title` or `weight`
# or
sortby:
variable: date # `date`, `updated`, `title` or `weight`
desc_title: false # sort by title in descending order
reverse: false # reverse the sort order
pages.pagination
Pagination is available for list pages (type is homepage, section or term).
pages:
pagination:
max: 5 # maximum number of entries per page
path: page # path to the paginated page
Disable pagination
Pagination can be disabled:
pages:
pagination: false
Or:
pages:
pagination:
enabled: false
pages.paths
Apply a custom path for all pages of a Section.
pages:
paths:
- section: <section’s ID>
path: <path of pages>
Path placeholders
:year:month:day:section:slug
Example:
pages:
paths:
- section: Blog
path: :section/:year/:month/:day/:slug # e.g.: /blog/2020/12/01/my-post/
# localized
languages:
- code: fr
name: Français
locale: fr_FR
config:
pages:
paths:
- section: Blog
path: blogue/:year/:month/:day/:slug # e.g.: /blogue/2020/12/01/mon-billet/
pages.frontmatter
Page front matter format (yaml by default, also accepts ini, toml and json).
pages:
frontmatter: yaml
pages.validation
Behavior when the front matter of a page does not match its schema:
warning: logs a warning and keeps the page;error(default): logs an error and skips the page;strict: the build fails;false: disables the validation.
pages:
validation: error
pages.schema
Schemas of the front matter, by Section or by page (* applies to all pages).
Schemas can also be written in the schemas directory, one file by Section or by page.
Each variable is defined by its type, or by a map of rules:
| Rule | Description |
|---|---|
type |
string, int, number, bool, date, list, map, scalar or mixed (default). |
required |
The variable must be defined (false by default). |
enum |
List of allowed values. |
pattern |
Regular expression that the value must match (string and scalar). |
min |
Minimum value (int, number), length (string) or count of items (list, map). |
max |
Maximum value (int, number), length (string) or count of items (list, map). |
items |
Type or definition of the items of a list (see lists and maps). |
fields |
Definitions of the variables of a map (see lists and maps). |
default |
Value applied when the variable is not defined. |
format |
What a string holds: text, markdown, url, email or path (see description of the variables). |
label |
Name of the variable, for the tools that edit the front matter. |
description |
Help text of the variable, for the tools that edit the front matter. |
pages:
schema:
'*':
title:
type: string
required: true
blog:
author: string # type shorthand
rating:
type: int
min: 1
max: 5
category:
type: string
enum: [news, tutorial]
default: news
tags:
type: list
items: string
max: 5
The length of a string (min and max rules) is counted in characters, not in bytes.
Lists and maps
The structure of a map and of the items of a list can be validated, at any depth:
fields: definitions of the variables of amap, with the same syntax as the variables of a page (type shorthand or map of rules, includingfieldsanditems). As a page, a map is open: undeclared variables are allowed.items: the type of the items (items: string), or the definition of the items (items: {type: map, fields: …}).
Scope of the rules:
- With a type of items (
items: string), theenumandpatternrules of the list apply to its items. - With a definition of items, only the rules of this definition apply to the items (
minandmaxof the definition apply to each item: length of a string, value of a number, etc.). An item can't be empty (null), except withitems: mixed, and therequiredanddefaultrules don't apply to items. - The
minandmaxrules of a list apply to its count of items. - A
mapwithfieldsdoesn't accept themin,max,enumandpatternrules (withoutfields,minandmaxapply to its count of variables). - A
defaultvalue of a variable of a map is applied when the map is defined but the variable is not (a missing map is not created), including in each item of a list.
Example: each image of an illustration must have a file name and an alternative text of 20 characters at least.
pages:
schema:
illustrations:
description: {type: string, required: true}
images:
type: list
min: 1
items:
type: map
fields:
file: {type: string, required: true, pattern: '^[\w-]+\.(png|jpe?g|gif|webp)$'}
alt: {type: string, required: true, min: 20}
An error gives the path of the invalid variable, from 0 for the first item of a list: The mandatory variable 'images › 1 › alt' is missing. (alternative text of the second image).
Schema of a page
A key of pages.schema can also be a page, for the pages that have their own variables (a home page, a résumé, etc.). The key is the ID of the page, without its language: the path of its file in the pages directory, without prefix, language and extension.
| File | Key |
|---|---|
index.md |
index |
cv.md, cv.en.md |
cv |
1-My project.md |
my-project |
blog/2024-05-01_post.md |
blog/post |
blog/index.md |
blog/index |
The variables are those of *, then of the section of the page, then of the page: the last ones override the others.
pages:
schema:
blog: # pages of the "blog" section
author: {type: string, required: true}
blog/index: # index of the "blog" section
intro: string
cv: # "cv.md" page, and its translations
skills:
type: list
items:
type: map
fields:
name: {type: string, required: true}
level: {type: int, min: 0, max: 100}
Description of the variables
The format, label and description rules describe a variable to the tools that edit the front matter (e.g. Cecil Desktop builds its form from the schema). They are accepted on any variable, also in fields and items.
format tells what a string holds:
| Format | Description |
|---|---|
text |
Text of several lines. |
markdown |
Text of several lines, rendered as Markdown by the template. |
url |
Absolute URL (https://cecil.app): validated. |
email |
Email address: validated. |
path |
Path of a file of the site (asset or static file): not checked. |
pages:
schema:
cv:
intro:
type: string
format: markdown
label: Introduction
description: Shown under the title of the page.
website: {type: string, format: url}
photo: {type: string, format: path, label: Photo}
label and description have no effect on the validation, and neither have the text, markdown and path formats.
Schemas directory
Instead of writing them in the configuration, schemas can be written in the schemas directory, at the root of the site: one YAML file (.yml or .yaml) by key of pages.schema, loaded automatically.
<mywebsite>
├─ pages
└─ schemas
├─ _all.yml <- '*': all pages
├─ blog.yml <- "blog" section
├─ cv.yml <- "cv.md" page
├─ index.yml <- home page
└─ blog
└─ index.yml <- "blog/index.md" page (key "blog/index")
- The path of a file in the directory, without its extension, is the key of the schema: a Section, or a page (
schemas/blog/post-1.ymlis the schema of theblog/post-1page). - The schema of all pages (
*) is the_all.ymlfile. - A key can't have two files (
blog.ymlandblog.yaml): this is an error. - A file holds the variables directly, as under
pages.schema.<key>, and an empty file is an empty schema.
# schemas/cv.yml
sections:
label: Sections
type: list
items:
type: map
fields:
title: {type: string, required: true}
text: {type: string, format: markdown}
is the same as:
pages:
schema:
cv:
sections:
# …
Each file is validated when the configuration is loaded: an error gives the name of the file and the path of the invalid variable in it (e.g. Invalid schema file "schemas/cv.yml"). As in pages.schema, a file whose key matches no Section and no page is ignored.
A theme can also have a schemas directory, for the variables its templates expect. Schemas are merged from the lowest to the highest priority:
schemasdirectories of the themes (a theme overrides the themes after it in the list);pages.schemaof theconfig.ymlof the themes (a theme overrides the themes after it in the list);schemasdirectory of the site;pages.schemaof the configuration of the site.
For a same key, variables are merged one by one, at each level and between themes: the definition of a variable replaces its previous definition as a whole (its rules are not merged, and enum lists are not combined), the other variables are kept.
# schemas/blog.yml
author: {type: string, required: true}
tags: {type: list, items: string}
# cecil.yml
pages:
schema:
blog:
author: string # "author" is now optional, "tags" is kept
pages.converter
Class used to convert the front matter and the Markdown body of pages (Cecil\Converter\Converter by default).
pages:
converter: Cecil\Converter\Converter
See Markdown converter to use your own.
pages.body
Page body options.
pages.body.parser
Markdown parser class (Cecil\Converter\Parsedown by default). It must extend Cecil\Converter\Parsedown: see Markdown parser to add your own syntax.
pages:
body:
parser: Cecil\Converter\Parsedown
pages.body.toc
Headers used to build the table of contents ([h2, h3] by default).
pages:
body:
toc: [h2, h3]
pages.body.anchors
Headings with an anchor link ([h2, h3] by default): an empty <a class="heading-anchor" href="#<id>"> element is added at the end of each of these headings that have an ID, to be styled by templates (e.g.: a # displayed on hover).
pages:
body:
anchors: [h2, h3] # set to false to disable anchors
pages.body.highlight
Enables code syntax highlighting (true by default).
pages:
body:
highlight: false # set to false to disable syntax highlighting
The highlighter engine can be changed with the engine option:
pages:
body:
highlight:
enabled: true # `true` by default
engine: tempest # `highlightjs` (default) or `tempest`
highlightjs: highlight.php, a PHP port of highlight.js (190+ languages,hljs-*CSS classes)tempest: tempest/highlight, a fast server-side highlighter (web languages: PHP, HTML, CSS, JavaScript, JSON, YAML, Twig, SQL, XML, etc.,hl-*CSS classes)
pages.body.images
Images handling options.
pages:
body:
images:
formats: [] # adds alternative image formats as `source` (e.g. `[avif, webp]`, empty array by default)
resize: 0 # resizes all images to <width> (in pixels, `0` to disable)
responsive: false # adds responsive image variants to the `srcset` attribute (`false` by default)
lazy: true # adds `loading="lazy"` attribute (`true` by default)
decoding: true # adds `decoding="async"` attribute (`true` by default)
caption: false # puts the image in a <figure> element and adds a <figcaption> containing the title (`false` by default)
placeholder: '' # fills the <img> background before loading ('color' or 'lqip', empty by default)
class: '' # sets a default class on each image (empty by default)
dark_suffix: ~ # suffix of the dark variant image (e.g. `.dark`), disabled by default
mobile_suffix: ~ # suffix of the mobile variant image (e.g. `.mobile`), disabled by default
mobile_media_query: '(max-width: 767px)' # media query of the mobile variant `<source>`
remote: # remote image handling (set to `false` to disable)
fallback: # path to the fallback image, stored in assets dir (empty by default)
pages.body.links
Links handling options.
pages:
body:
links:
embed:
enabled: false # turns links into embedded content if possible (`false` by default)
video: [mp4, webm] # video files extensions
audio: [mp3, ogg, wav] # audio files extensions
external:
blank: false # if true open external link in new tab
noopener: true # if true add "noopener" to `rel` attribute
noreferrer: true # if true add "noreferrer" to `rel` attribute
nofollow: false # if true add "nofollow" to `rel` attribute
pages.body.excerpt
Excerpt handling options.
pages:
body:
excerpt:
separator: excerpt|break # string to use as separator (`excerpt|break` by default)
capture: before # part to capture, `before` or `after` the separator (`before` by default)
pages.default
Default pages are pages without content file (front matter only), indexed by ID, each one with a path and some front matter variables.
Cecil provides built-in default pages (from built-in templates):
pages:
default:
index:
path: ''
title: Home
published: true
404:
path: 404
title: Page not found
layout: 404
uglyurl: true
published: true
excluded: true
robots:
path: robots
title: Robots.txt
layout: robots
output: txt
published: true
excluded: true
multilingual: false
sitemap:
path: sitemap
title: XML sitemap
layout: sitemap
output: xml
changefreq: monthly
priority: 0.5
published: true
excluded: true
multilingual: false
xsl/sitemap:
path: xsl/sitemap
layout: sitemap
output: xsl
uglyurl: true
published: true
excluded: true
xsl/atom:
path: xsl/atom
layout: feed
output: xsl
uglyurl: true
published: true
excluded: true
xsl/rss:
path: xsl/rss
layout: feed
output: xsl
uglyurl: true
published: false
excluded: true
Each one can be:
- disabled:
published: false - excluded from list pages:
excluded: true - excluded from localization:
multilingual: false
You can also add your own pages (a theme can do the same in its config.yml):
pages:
default:
code:
path: code
redirect: https://github.com/ArnaudLigny
Like any other page, a default page is listed (e.g.: in site.pages.showable, in the sitemap, on the homepage): set excluded: true to keep a technical page (JSON index, manifest, etc.) out of lists.
pages.generators
Generators are used by Cecil to create additional pages (e.g.: sitemap, feed, pagination, etc.) from existing pages, or from other sources like the configuration file or external sources.
Generators are indexed by name and run in ascending order of their priority. Below is the list of generators provided by Cecil:
pages:
generators:
DefaultPages: { class: Cecil\Generator\DefaultPages, priority: 10 }
ExternalBody: { class: Cecil\Generator\ExternalBody, priority: 30 }
Section: { class: Cecil\Generator\Section, priority: 40 }
Taxonomy: { class: Cecil\Generator\Taxonomy, priority: 50 }
Homepage: { class: Cecil\Generator\Homepage, priority: 60 }
Pagination: { class: Cecil\Generator\Pagination, priority: 70 }
Alias: { class: Cecil\Generator\Alias, priority: 80 }
Redirect: { class: Cecil\Generator\Redirect, priority: 90 }
A built-in generator can be disabled or moved by its name:
pages:
generators:
Redirect: false # disabled
Section: { priority: 45 } # moved
See Extensions for the full syntax.
pages.subsets
Subsets are used to render a part of the pages collection, based on a specific path, language or output format, with the command:
cecil build --render-subset=<name>
pages:
subsets:
<name>:
path: <path> # glob or string path (e.g.: `blog/*`, `blog`)
language: <language> # language code (e.g.: `en`, `fr`)
output: <output> # output format (e.g.: `html`, `atom`)
Example:
pages:
subsets:
blog_en:
path: blog
language: en
output: html
search_index:
path: '*'
output: json