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

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

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

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