Sur cette page

Contenu

Il existe différents types de contenu dans Cecil :

Pages: Les pages constituent le contenu principal du site, rédigé en Markdown.; Les pages doivent être organisées de manière à refléter le site Web généré.; Les pages peuvent être organisées en Sections (dossiers racine) (ex. : « Blog », « Projet », etc.).
Assets: Les assets sont des fichiers transformés (c.-à-d. : images redimensionnées, Sass compilé, scripts minifiés, etc.) avec la fonction de template asset().
Static files: Les fichiers statiques sont copiés tels quels dans le site généré (ex. : static/file.pdf -> file.pdf).
Data files: Les fichiers de données sont des collections de variables personnalisées, exposées dans les templates via site.data.

Organisation des fichiers

Arborescence du système de fichiers

Organisation des fichiers du projet.

<monsiteweb>
├─ pages
|  ├─ blog            <- Section
|  |  ├─ post-1.md    <- Page dans Section
|  |  └─ post-2.md
|  ├─ projects
|  |  └─ project-a.md
|  └─ about.md        <- Page racine
├─ assets
|  ├─ styles.scss     <- Fichier d'asset
|  └─ logo.png
├─ static
|  └─ file.pdf        <- Fichier statique
└─ data
   └─ authors.yml     <- Collection de données

Arborescence du site généré

Résultat de la génération.

<monsiteweb>
└─ _site
   ├─ index.html               <- Page d'accueil générée
   ├─ blog/
   |  ├─ index.html            <- Liste des articles générée
   |  ├─ post-1/index.html     <- Article de blog
   |  └─ post-2/index.html
   ├─ projects/
   |  ├─ index.html            <- Liste des projets générée
   |  └─ project-a/index.html  <- Projet individuel
   ├─ about/index.html         <- Page "À propos"
   ├─ styles.css
   ├─ logo.png
   └─ file.pdf

Routage basé sur les fichiers

Les fichiers Markdown du répertoire pages activent un routage basé sur les fichiers. Cela signifie que l’ajout, par exemple, de pages/my-projects/project-a.md le rendra accessible à l’URL /project-a dans votre navigateur.

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

Pages

Une page est un fichier composé d’un front matter et d’un body.

Front matter

Le front matter est une collection de variables (au format clé/valeur) entourée par ---.

Exemple :

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

Corps (body)

Le body est le contenu principal d’une page ; il peut être écrit en Markdown ou en texte brut.

Exemple :

# Header

[toc]

## Sub-Header 1

Lorem ipsum dolor [sit amet](https://example.com), consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<!-- excerpt -->
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Sub-Header 2

![Description](/image.jpg "Title")

## Sub-Header 3

:::tip
This is an advice.
:::

Markdown

Cecil prend en charge le format Markdown, ainsi que Markdown Extra.

Cecil fournit aussi des fonctionnalités supplémentaires pour enrichir votre contenu, voir ci-dessous.

Attributs

Avec Markdown Extra, vous pouvez définir un id, une classe et des attributs personnalisés sur certains éléments à l’aide d’un bloc d’attributs.
Par exemple, placez le(s) attribut(s) souhaité(s) après un en-tête, un bloc de code délimité, un lien ou une image en fin de ligne, entre accolades, comme ceci :

## En-tête {#id .class attribute=value}

Pour un élément en ligne, comme un lien, vous devez utiliser un retour à la ligne après l’accolade fermante :

Lorem ipsum [dolor](url){attribute=value} 
sit amet.

Liens

Vous pouvez créer un lien avec la syntaxe [Texte](url) ; url peut être un chemin, un chemin relatif vers un fichier Markdown, une URL externe, etc.

Exemple :

[Link to a path](/about/)
[Link to a Markdown file](../about.md)
[Link to Cecil website](https://cecil.app)

Lien vers une page

Vous pouvez facilement créer un lien vers une page avec la syntaxe [Titre de page](page:page-id).

Exemple :

[Link to a blog post](page:blog/post-1)

Externe

Par défaut, les liens externes ont la valeur suivante pour l’attribut rel : noopener noreferrer.

Exemple :

<a href="<url>" rel="noopener noreferrer">Link to another website</a>

Vous pouvez modifier ce comportement avec les options pages.body.links.external.

Liens intégrés

Vous pouvez laisser Cecil essayer de transformer un lien en contenu embarqué en utilisant l’attribut {embed} ou en activant l’option de configuration globale pages.body.links.embed.enabled à true.

Exemple :

[CECIL : LE générateur de SITES STATIQUES en PHP](https://www.youtube.com/watch?v=ur8koU0iYvc){embed}

Local video/audio files

Cecil peut aussi créer des éléments HTML vidéo et audio, selon l’extension du fichier.

Exemple :

[Video file](video.mp4){embed controls poster=/images/video-test.png}
[Audio file](song.mp3){embed controls}

Est converti en :

<video src="/video.mp4" controls poster="/images/video-test.png" style="max-width:100%;height:auto;"></video>
<audio src="/song.mp3" controls></audio>

Images

Pour ajouter une image, utilisez un point d’exclamation (!) suivi d’une description alternative entre crochets ([]), puis du chemin ou de l’URL de l’image entre parenthèses (()).
Vous pouvez facultativement ajouter un titre entre guillemets.

![Alternative description](/image.jpg "Image title")

Lazy loading

Cecil ajoute l’attribut loading="lazy" à chaque image.

Exemple :

![](/image.jpg)

Est converti en :

<img src="/image.jpg" loading="lazy">

Decoding

Cecil ajoute l’attribut decoding="async" à chaque image.

Exemple :

![](/image.jpg)

Est converti en :

<img src="/image.jpg" decoding="async">

Redimensionnement

Chaque image du body peut être redimensionnée automatiquement en définissant une largeur inférieure à celle d’origine, avec l’attribut additionnel {width=X}.

Exemple :

![](/image.jpg){width=800}

Est converti en :

<img src="/thumbnails/800/image.jpg" width="800" height="600">

Formats

Si l’option formats est définie, des images alternatives sont créées et ajoutées.

Exemple :

![](/image.jpg)

Peut être converti en :

<picture>
  <source srcset="/image.avif" type="image/avif">
  <source srcset="/image.webp" type="image/webp">
  <img src="/image.jpg">
</picture>

Responsive

Si l’option responsive est activée, alors toutes les images du body seront automatiquement rendues « responsive ».

Exemple :

![](/image.jpg){width=800}

sera converti en :

<img src="/thumbnails/800/image.jpg" width="800" height="600"
  srcset="/thumbnails/320/image.jpg 320w,
          /thumbnails/640/image.jpg 640w,
          /thumbnails/800/image.jpg 800w"
  sizes="100vw"
>

L’attribut sizes prend la valeur de l’option de configuration assets.images.responsive.sizes.default, mais peut être modifié en créant une nouvelle entrée nommée d’après une class ajoutée à l’image.

Exemple :

assets:
  images:
    responsive:
      sizes:
        default: 100vw
        my_class: "(max-width: 800px) 768px, 1024px"

![](/image.jpg){.my_class}

CSS class

Vous pouvez définir une valeur par défaut pour l’attribut class de chaque image avec l’option class.

Caption

Le titre optionnel peut être utilisé pour créer automatiquement une légende (figcaption) en activant l’option caption.

Exemple :

![](/images/img.jpg "Title")

Est converti en :

<figure>
  <img src="/image.jpg" title="Title">
  <figcaption>Title</figcaption>
</figure>

Placeholder

Comme les images sont généralement des ressources plus lourdes et plus lentes, et qu’elles ne bloquent pas le rendu, il est préférable de donner aux utilisateurs quelque chose à voir pendant qu’ils attendent leur chargement.

L’attribut placeholder accepte 2 options :

color: affiche un fond coloré (basé sur la couleur dominante de l’image)
lqip: Low-Quality Image Placeholder

Exemples :

![](/images/img.jpg){placeholder=color}
![](/images/img.jpg){placeholder=lqip}

Table des matières

Vous pouvez ajouter une table des matières avec la syntaxe Markdown suivante :

[toc]

Extrait

Un extrait peut être défini dans le body avec l’une des balises suivantes : excerpt ou break.

Exemple :

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

Utilisez ensuite le filtre excerpt_html dans votre template.

Notes

Créez un bloc de Note (info, astuce, important, etc.).

Exemple :

:::tip
**Tip:** This is an advice.
:::

Est converti en :

<aside class="note note-tip">
  <p>
    <strong>Tip:</strong> This is an advice.
  </p>
</aside>

Autres exemples :

Coloration syntaxique

Active le surligneur syntaxique des blocs de code en définissant l’option pages.body.highlight.enabled à true.

Exemple :

```php
echo "Hello world";
```

Est rendu en :

echo "Hello world";

Texte inséré

Représente une plage de texte qui a été ajoutée.

++text++

Est converti en :

<ins>text</ins>

Variables

Le front matter peut contenir des variables personnalisées appliquées à la page courante.

Il doit se trouver au tout début du fichier et être un YAML valide.

Variables prédéfinies

Variable	Description	Valeur par défaut	Exemple
`title`	Titre	Nom de fichier sans extension.	`Post 1`
`layout`	Template	Voir Lookup rules.	`404`
`date`	Date de création	Date de création du fichier (objet PHP DateTime).	`2019/04/15`
`section`	Section	Section de la page.	`blog`
`path`	Chemin	Path de la page.	`blog/post-1`
`slug`	Slug	Slug de la page.	`post-1`
`published`	Publié ou non	`true`.	`false`
`draft`	Brouillon ou non	`false`.	`true`

updated

La variable updated sert à définir la date de dernière modification d’une page.

Exemple :

---
updated: 2026-02-02
---

Une page peut être ajoutée à un menu.

Le nom de l’entrée est le title de la page et l’URL est le path de la page.

Une même page peut être ajoutée à plusieurs menus, et la position de chaque entrée peut être définie avec la clé weight (la plus faible en premier).

Exemples :

---
menu: main
---

---
menu: [main, navigation] # same page in multiple menus
---

---
menu:
  main:
    weight: 10
  navigation:
    weight: 20
---

Taxonomie

La taxonomie permet de connecter, relier et classer le contenu de votre site Web.
Dans Cecil, ces termes sont regroupés dans des vocabulaires.

Les vocabulaires sont déclarés dans la Configuration.

Une page peut contenir plusieurs vocabulaires (ex. : tags) et termes (ex. : Tag 1).

Exemple :

---
tags: ["Tag 1", "Tag 2"]
---

Planification

Planifie la publication des pages.

Exemple :

La page sera publiée si la date courante est >= 2023-02-07 :

schedule:
  publish: 2023-02-07

Cette page est publiée si la date courante est <= 2022-04-28 :

schedule:
  expiry: 2022-04-28

redirect

Comme son nom l’indique, la variable redirect sert à rediriger une page vers une URL dédiée.

Exemple :

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

alias

Un alias est une redirection vers la page courante.

Exemple :

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

Dans l’exemple précédent, contact/ redirige vers about/.

output

Définit le format de sortie de la page.

Les formats disponibles sont : html, atom, rss, json, xml, etc.
Vous pouvez définir un ou plusieurs formats dans un tableau.

Il n’est pas obligatoire de définir un format de sortie, mais si vous le faites, il doit correspondre à l’un des formats disponibles définis dans la Configuration.

Exemple :

---
output: [html, atom]
---

external

Une page avec une variable external tente de récupérer le contenu de la ressource ciblée.

Exemple :

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

Préfixe de fichier

Le nom de fichier peut contenir un préfixe pour définir les variables date ou weight de la page (utilisé par sortby).

date

Le date prefix est utilisé pour définir la date de la page et doit être un format de date valide (c.-à-d. : « YYYY-MM-DD »).

Exemple :

Dans « 2019-04-23_My blog post.md » :

le préfixe est « 2019-04-23 »
la date de la page est « 2019-04-23 »
le title de la page est « My blog post »

weight

Le weight prefix est utilisé pour définir l’ordre de tri de la page et doit être une valeur entière valide.

Exemple :

Dans « 1_The first project.md » :

le préfixe est « 1 »
le weight de la page est « 1 »
le title de la page est « The first project »

Section

Certaines variables dédiées peuvent être utilisées dans une Section personnalisée (c.-à-d. : <section>/index.md).

sortby

L’ordre des pages dans une Section peut être modifié.

Valeurs disponibles :

date: plus récentes en premier
title: ordre alphabétique
weight: plus léger en premier

Exemple :

---
sortby: title
---

More options:

---
sortby:
  variable: date    # "date", "updated", "title" or "weight"
  desc_title: false # used with "date" or "updated" variable value to sort by desc title order if items have the same date
  reverse: false    # reversed if true
---

pagination

La configuration globale de pagination est utilisée par défaut, mais vous pouvez la modifier pour une Section donnée.

Exemple :

---
pagination:
  max: 5
  path: "page"
  pagination: false
---

cascade

Toutes les variables de cascade sont ajoutées au front matter de toutes les sous-pages.

Exemple :

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

circular

Définissez circular à true pour activer la navigation circulaire avec page.<prev/next>.

Exemple :

---
circular: true
---

Page d'accueil

Comme une autre section, la Page d'accueil prend en charge la configuration sortby et pagination.

pagesfrom

Définissez un nom de Section valide dans pagesfrom pour utiliser la collection de pages de cette Section dans la Page d'accueil.

Exemple :

---
pagesfrom: blog
---

excluded

Définissez excluded à true pour masquer une page des pages de liste (c.-à-d. : Home page, Section, Sitemap, etc.).

Exemple :

---
excluded: true
---

Multilingue

Si vos pages sont disponibles en plusieurs langues, il existe 2 façons différentes de le définir :

Via le nom de fichier

C’est la méthode la plus courante pour traduire une page depuis la langue principale vers une autre langue.

Il suffit de dupliquer la page de référence et de lui ajouter en suffixe le code de la langue cible (ex. : fr).

Exemple :

├─ about.md    # the reference page
└─ about.fr.md # the french version (`fr`)

Vous pouvez changer l’URL de la page traduite avec la variable slug dans le front matter. Par exemple :

---
slug: a-propos
---
# about.md    -> /about/
# about.fr.md -> /fr/a-propos/

Via le front matter

Si vous souhaitez créer une page dans une langue autre que la langue principale, sans qu’elle soit la traduction d’une page existante, vous pouvez utiliser la variable language dans son front matter.

Exemple :

---
language: fr
---

Lier les pages traduites

Chaque page traduite référence les pages dans les autres langues.

Cette collection de pages est disponible dans les templates via la variable suivante :

{{ page.translations }}

La variable langref est fournie par défaut, mais vous pouvez la modifier dans le front matter :

---
langref: my-page-ref
---

Contenu dynamique

Avec cette fonctionnalité expérimentale, vous pouvez utiliser des variables et des shortcodes dans le body.

Pour cela, vous devez inclure un template spécifique :

{{ include(page.content_template) }}

(au lieu de {{ page.content }})

Afficher des variables

Les variables du front matter peuvent être utilisées dans le body avec la syntaxe de template {{ page.variable }}.

Exemple :

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

Experimental

Shortcodes

Les shortcodes sont des helpers pour créer du contenu dynamique.

Experimental

Shortcodes intégrés

2 shortcodes sont disponibles par défaut :

YouTube

{{ shortcode.youtube(id) }}

id: ID de la vidéo YouTube

Exemple :

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

GitHub Gist

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

user: nom d’utilisateur GitHub
id: ID du Gist

Exemple :

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

Shortcode personnalisé

Un shortcode est une macro Twig que vous devez ajouter dans un template nommé shortcodes.twig.

Exemple :

shortcodes.twig:

{% extends 'extended/macros.twig' %}

{% block macros %}

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

{% endblock %}

Suggérer une modification

← Démarrage rapide Templates →

Sur cette page

Organisation des fichiers
Pages
Markdown
Variables
Multilingue
Contenu dynamique