Cecil logo

Content

There is 3 kinds of content in Cecil:

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

Files organization

Your content should be organized in a manner that reflects the rendered website.

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 uglyurl: 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

Predefined variables.

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.

A Page can be added to a menu, as an entry.

In the following example, the menu is navigation: 

---
menu: navigation
---

A same Page could be added to severals menus, and the position of each entry could be defined with the weight key (the lightest first).

See Menus configuration for details.

Examples: 

---
menu: [main, navigation]
---
---
menu:
  main:
    weight: 10
  navigation:
    weight: 20
---

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 the page from list pages (like Home page, Section, Sitemap, etc.). 

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

If the page’s language is different from the site main language (see language in Configuration) there is two options to specify it: file name and front matter.

Experimental

Language code in the file name

Add the language code in the file name.

Example: 

blog-post.fr.md

Language code in the front matter

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

Example: 

---
language: fr
---

Dynamic content

You can use variables and shortcodes in the body content.

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

{% include page.content_template %}

Experimental

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

Shortcodes are helpers to create dynamic content.

Built-in shortcodes

2 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') }}

Custom shortcode

A shortcode is a Twig macro you must add 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 →