Cecil logo Cecil
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 a map, with the same syntax as the variables of a page (type shorthand or map of rules, including fields and items). 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), the enum and pattern rules of the list apply to its items.
  • With a definition of items, only the rules of this definition apply to the items (min and max of the definition apply to each item: length of a string, value of a number, etc.). An item can't be empty (null), except with items: mixed, and the required and default rules don't apply to items.
  • The min and max rules of a list apply to its count of items.
  • A map with fields doesn't accept the min, max, enum and pattern rules (without fields, min and max apply to its count of variables).
  • A default value 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.yml is the schema of the blog/post-1 page).
  • The schema of all pages (*) is the _all.yml file.
  • A key can't have two files (blog.yml and blog.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:

  1. schemas directories of the themes (a theme overrides the themes after it in the list);
  2. pages.schema of the config.yml of the themes (a theme overrides the themes after it in the list);
  3. schemas directory of the site;
  4. pages.schema of 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)

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:

  1. disabled: published: false
  2. excluded from list pages: excluded: true
  3. 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