Content

There is 3 kinds of content in Cecil:

Pages (Markdown files in content/)
Static files (images, CSS, PDF, etc. in static/)
Data files (custom variables collections in data/)

Files organization

File system tree

<mywebsite>
├─ content
|  ├─ blog               <- Section
|  |  ├─ post-1.md       <- Page in Section
|  |  └─ post-2.md
|  ├─ projects
|  |  └─ project-1.md
|  └─ about.md           <- Page in the root
├─ static
|  ├─ logo.png           <- Static file
|  └─ css
|     └─ style.scss
└─ data
   ├─ authors.yml        <- Data collection
   └─ galleries
      └─ gallery-1.json

Each folder in the root of content/ is called a Section (ie: « Blog », « Project », etc.)

Files in static/ are copied as is in the root of the built website (ie: static/images/logo.png -> images/logo.png) or manipulated by asset()

Content of files in data/ are exposed in templates with {{ site.data }}

Built website tree

<mywebsite>
└─ _site
   ├─ index.html               <- Generated home page
   ├─ blog/
   |  ├─ index.html            <- Generated list of posts
   |  ├─ post-1/index.html     <- A blog post
   |  └─ post-2/index.html
   ├─ projects/
   |  ├─ index.html            <- Generated list of projects
   |  └─ project-1/index.html
   ├─ about/index.html
   └─ static/
      ├─ logo.png
      └─ css
         └─ style.css

By default each page is generated as filename-slugified/index.html to get a “beautiful“ URL like https://mywebsite.tld/blog/post-1/.

To get an “ugly” URL, use uglify: true in front matter (ie: 404.html instead of 404/index.html).

You can override Section’s default variables by creating an index.md file in the Section’s directory (ie: blog/index.md).

File VS URL structure

File:
                 content/my-projects/project-1.md
                        └───── filepath ──────┘
URL:
    ┌───── baseurl ─────┬─────── path ────────┐
     https://example.com/my-projects/project-1/index.html
                        └─ section ─┴─ slug ──┘

Page anatomy

Your page are composed with a front matter (“meta datas”) and a body (main content).

Front matter

The front matter is the way to store variables in a Page, in key/value format.

It must be the first thing in the file and must be a valid YAML.
Separators must be ---,  or +++.

Example:

---
title: "The title"
date: 2019-02-21
tags: [tag 1, tag 2]
customvar: "Value of customvar"
---

Body

Body is the main content of the page, it could be written in Markdown, in Markdown Extra or in plain text.

Example:

---
title: "The title"
date: 2019-02-21
tags: [tag 1, tag 2]
customvar: "Value of customvar"
---
# Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Excerpt

An excerpt can be defined in body with one of those following tags: excerpt or break.

Example:

Introduction.
<!-- excerpt -->
Main content.

Images

Resize

Experimental

Images in the body can be resized with the following syntax: ?resize=300.

Ratio is preserved, the original file is not altered and the resized version is stored in /images/thumbs/<resize>/image.ext.

This feature requires GD extension (otherwise it only add a width HTML attribute).

Example:

![Alt](/cecil-logo.png?resize=300 'Title')

Responsive

Experimental

Images in the body can be "responsived" with the following syntax: ?responsive.

Example:

![Alt](/cecil-logo-1000.png?responsive 'Title')

<img src="/cecil-logo-1000.png" alt="Alt" title="Title"
  srcset="/images/thumbs/456/cecil-logo-1000.png 456w,
          /images/thumbs/592/cecil-logo-1000.png 592w,
          /images/thumbs/728/cecil-logo-1000.png 728w,
          /images/thumbs/864/cecil-logo-1000.png 864w,
          /cecil-logo-1000.png 1000w"
   sizes="(max-width: 1000px) 100vw, 1000px">

Variables

The front matter can contains custom variables or override predefined variables.

Predefined

Variable	Description	Default value
`title`	Title	File name without extension (ie: `Post 1`).
`layout`	Layout	See Templates Lookup rules (ie: `404`).
`date`	Date (ie: `2019/04/15`)	File creation date (PHP DateTime object).
`updated`	Date of modification	File modification date (PHP DateTime object).
`section`	Section	Page's Section (ie: `blog`).
`path`	Path	Page's path (ie: `blog/post-1`).
`slug`	Slug	Page's slug (ie: `post-1`).
`published`	Draft or published?	`true`.
`draft`	Draft or published?	`false`.
`output`	Rendered format	`html`.

Taxonomy

Taxonomies are declared in the Configuration.

Each page can contain severals terms (ie: Tag 1) of each taxonomies’ vocabulary (ie: tags).

Example:

---
tags:
  - "Tag 1"
  - "Tag 2"
---

Section

Dedicated variables can be used in a custom Section (ie: blog/index.md).

sortby

The order of Pages can be changed for a Section.

Available values are:

date: more recent first
title: alphabetic order
weight: lightest first

Example:

---
sortby: title
---

pagination

Global pagination configuration can be overridden for a Section.

Example:

---
pagination:
  max: 2
  path: "p"
---

cascade

Any values in cascade variable will be merged into front matter of all sub pages.

Note: existing sub pages variables are not overridden.

Example:

---
cascade:
  banner: image.jpg
---

circular

Set circular to true to enable circular pagination with page.<prev/next>.

---
circular: true
---

exclude

Set exclude to true to hide a page from her Section.

---
exclude: true
---

exclude is different from published: an excluded page is published but hidden from the section pages' list.

redirect

As indicated by its name, the redirect variable is used to redirect a page to a dedicated URL.

The default template is redirect.html.twig.

---
redirect: "https://arnaudligny.fr/"
---

alias

alias is used to create a redirection to the current page.

In the following example contact/ redirects to about/:

---
title: "About"
alias:
  - contact
---

external

A page with an external variable try to fetch the content of the pointed resource.

---
external: "https://raw.githubusercontent.com/Cecilapp/Cecil/master/README.md"
---

File prefix

The filename can contain a prefix to define Page's date or weight (used by sortby).

The prefix is not included in the Pages's title variable.
Available prefix separator are -, _ and ..

date

The date prefix is used to set the Page's creation date, and must be a valid date format (YYYY-MM-DD).

Example:

In 2019-04-23-A blog post.md:

the prefix is 2019-04-23
the Page's date is 2019-04-23
the Page's title is A blog post

weight

The weight prefix is used to set the Page's sort order, and must be a valid integer value.

Example:

In 1.The first project.md:

the prefix is 1
the Page's weight is 1
the Page's title is The first project

Localized content

Experimental

If the page's language is different from the site main language (see language in Configuration) there is two options to specify it:

1. Language code in the file name

Add the language code in the file name.

Example:

blog-post.fr.md

2. Language code in the front matter

Add the variable language with language code as value in the front matter.

Example:

---
language: fr
---

Variables and shortcodes

Experimental

Need a specific template

To be able to use variables and shortcodes you must include a specific template instead of {{ page.content }}:

{% include page.content_template %}

Display variables

Front matter variables can be use in the body with the template's syntax {{ page.variable }}.

Example:

--
var: 'value'
---
The value of `var` is {{ page.var }}.

Shortcodes

Built-in shortcodes

Two shortcodes are available by default:

YouTube

{{ shortcode.youtube(id) }}

id: YouTube video ID

Example:

{{ shortcode.youtube('NaB8JBfE7DY') }}

GitHub Gist

{{ shortcode.gist(user, id) }}

user: GitHub user name
id: Gist ID

Example:

{{ shortcode.gist('Narno', 'fbe791e05b93951ffc1f6abda8ee88f0') }}

Create your own shortcodes

A shortcode is a Twig macro you must create in a template named shortcodes.twig.

Example:

shortcodes.twig:

{% extends 'macros.twig' %}

{% block macros %}

{# the "foo" shortcode #}
{% macro foo(bar = 'bar') %}
<strong>{{ bar }}</strong>
{% endmacro %}

{% endblock %}

Suggest a modification

← Quick Start Templates →

Content

Files organization

File system tree

Built website tree

File VS URL structure

Page anatomy

Front matter

Body

Excerpt

Images

Resize

Responsive

Variables

Predefined

menu

Taxonomy

Section

sortby

pagination

cascade

circular

exclude

redirect

alias

external

File prefix

date

weight

Localized content

1. Language code in the file name

2. Language code in the front matter

Variables and shortcodes

Need a specific template

Display variables

Shortcodes

Built-in shortcodes

YouTube

GitHub Gist

Create your own shortcodes