Table of contents

Content

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

Files organization

Markdown files are called Pages and should be stored in content/
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

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

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

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

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, the menu is main (default menu):

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

alias is used to create a redirection from a virtual 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

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

`sortby`

date, title or weight.

`pagination`

See Configuration.

Example

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

File prefix

A content filename can contain a prefix to define Page's date or weight (sort order).

Note: The prefix is not included in the Pages's title.

`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

Available prefix separator: -, _ or ..

Localized content (beta)

If the language of a page is different from the site language (see language in Configuration) you must specify it in the front matter:

---
language: fr
---

Variables and macros (beta)

Variables and macros in Page's body is a beta feature.

Display variables

Example

--
layout: macro
var: 'value'
---

page.var: {{ page.var }}

{% set foo = 'bar' %}
foo: {{ foo }}

Embed macros

2 macros available for the moment:

YouTube

{{ macro.youtube(id) }}

id: YouTube video ID

GitHub Gist

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

user: GitHub username
id: Gist ID

Example

---
layout: macro
---

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

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

Specific template

To be able to use variables and macros you must include the specific sub-template {% include page.content_template %} instead of {{ page.content }} in your template.

Suggest a modification

Quick Start Templates