Table of contents

Content

Content is files writen in Markdown (or plain text files) and static files (like CSS style sheet).

Files organization

  1. Markdown files are called Pages and should be stored in content/
  2. Static files should be stored in static/

Filesystem tree

<mywebsite>
├─ content
|  ├─ blog             <- A Section
|  |  ├─ post-1.md     <- A Page in Section
|  |  └─ post-2.md
|  ├─ projects         <- Another Section
|  |  └─ project-1.md
|  └─ about.md         <- A Page in the root
└─ static
   ├─ robots.txt       <- A static file
   └─ styles
      └─ main.scss

Notes

  1. Each folder in the root is called a Section (ie: « Blog », « Project »).
  2. Static files are copied as is in the root of the built website (ie: static/robots.txt -> robots.txt).

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/
      ├─ robots.txt
      └─ styles
         └─ main.css

Notes

  1. By default each page is generated as filename-slugified/index.html to get a “beautiful“ URL like https://mywebsite.tld/blog/post-1/.
  2. To get an “ugly” URL, use uglify: true in front matter (ie: 404.html instead of 404/index.html).
  3. 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

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.

Example

---
title: "The title"
date: 2019-02-21
---

Separator should be ---, <!-- --> or +++.

Body

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

Excerpt

An excerpt can be defined in body with the following tag:

<!-- excerpt -->

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.

Variables

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 Lookup rules in Templates (ie: 404).
date Date (ie: 2019/04/15) File creation datetime (PHP DateTime object).
updated Date of modification File modification datetime (PHP DateTime object).
section Section Page's Section (ie: blog). Can’t be overrided.
path and url Path = URL 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.

menu

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

In the following example, menu is main (default menu created):

---
menu: main
---

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

Example

---
menu:
  main:
    weight: 999
  secondary
---

See Configuration for details.

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

It’s used to create a redirection from the alias page to the current page.

In the following example the page contact/ redirects to about/:

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

external

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

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

Taxonomy

Taxonmies 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 (section/index.md).

sortby

date, title or weight.

pagination

See Configuration.

Example

---
sortby: title
pagination:
  max: 5
  path: "page"
---

Suggest a modification

Quick Start Templates