Sur cette page

Attributs
Liens
Images
Ancres des titres
Table des matières
Extrait
Notes
- Notes imbriquées
- Templates
Coloration syntaxique
Texte inséré

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 titre, un bloc de code délimité, un lien ou une image en fin de ligne, entre accolades, comme ceci :

## Titre {#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

Cecil peut essayer de transformer un lien en contenu intégré en utilisant l’attribut {embed} ou en définissant 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}

Fichiers vidéo/audio locaux

Cecil peut aussi créer des éléments HTML <video> et <audio>, selon l’extension du fichier (mp4 et webm pour la vidéo, mp3, ogg et wav pour l’audio, voir pages.body.links.embed).

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;background-color:#d8d8d8;"></video>
<audio src="/song.mp3" controls></audio>

Avec {embed=false} (ou lorsque l’intégration est désactivée), un fichier vidéo/audio local reste un lien, mais son URL pointe vers le fichier publié (avec empreinte si assets.fingerprint est activé).

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

Chargement différé

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

Exemple :

![](/image.jpg)

Est converti en :

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

Décodage

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

La prise en charge de libvips est facultative et n’est pas incluse dans cecil.phar. Pour l’utiliser, Cecil doit être installé avec Composer et il faut :

libvips installé sur le système
l’extension PHP FFI activée
le paquet intervention/image-driver-vips installé avec Cecil

Si Cecil est une dépendance de votre projet (voir Bibliothèque) :

composer require intervention/image-driver-vips

Si Cecil est installé globalement :

composer global require cecil/cecil intervention/image-driver-vips

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/480/image.jpg 480w,
          /thumbnails/640/image.jpg 640w,
          /thumbnails/768/image.jpg 768w,
          /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}

Classe CSS

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

Légende

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

Exemple :

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

Est converti en :

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

Image localisée

Pour les pages traduites, Cecil recherche d’abord un fichier suffixé par la langue lors de la résolution des chemins d’image Markdown.

Exemple :

![](/images/cecil-logo.png)

Avec une page française (fr), Cecil essaie d’abord /images/cecil-logo.fr.png, puis revient à /images/cecil-logo.png.

Variantes sombre et mobile

Si l’option dark_suffix est définie (ex. : .dark), Cecil recherche une variante sombre de chaque image (ex. : image.dark.jpg à côté de image.jpg) et l’ajoute en tant que <source media="(prefers-color-scheme: dark)"> dans un élément <picture>.

De la même manière, si l’option mobile_suffix est définie (ex. : .mobile), Cecil recherche une variante mobile de chaque image (ex. : image.mobile.jpg) et l’ajoute en tant que <source> avec la media query mobile_media_query.

Espace réservé (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 deux valeurs :

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}

Ancres des titres

Un lien d’ancre est ajouté à la fin des titres h2 et h3 (voir l’option pages.body.anchors), pour faire un lien vers un titre d’une page :

<h2 id="heading">Heading<a class="heading-anchor" href="#heading" aria-hidden="true" tabindex="-1"></a></h2>

Le lien est vide : les templates par défaut affichent un # au survol.

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’un des commentaires HTML suivants :  ou  (voir l’option pages.body.excerpt).

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

Est converti en :

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

Autres exemples :

Notes imbriquées

Une note est fermée par une ligne composée d’au moins autant de : que sa ligne d’ouverture : pour imbriquer des notes, utilisez une clôture plus longue pour la note parente (::::, puis ::::: pour un troisième niveau, etc.).

::::info
Avant.

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

Après.
::::

Une clôture plus longue permet aussi d’afficher la syntaxe des notes dans un bloc de code, à l’intérieur d’une note.

Templates

Une note est rendue avec le template partials/notes/<type>.html.twig, s’il existe (dans les layouts/ du site, dans un thème ou intégré à Cecil), à la place de l’élément <aside>.

Cecil fournit des templates pour les types suivants, rendus sans JavaScript : un thème peut les mettre en forme, les surcharger et y ajouter de l’interactivité. Contrairement aux autres notes, leur élément racine est un <div class="note note-<type>"> (et non un <aside>), car leur contenu fait partie du contenu principal.

Type	Éléments	Rendu
`tabs`	un par titre `####`	panneaux empilés (`<section class="note-tab">`)
`code-group`	un par titre `####`, ou un par bloc de code (intitulé avec son langage)	comme `tabs`
`steps`	un par titre `####`	liste ordonnée (`<ol class="note-steps-list">`)
`accordion`	un par titre `####`	`<details class="note-accordion-item">`
`cards`	un par entrée de liste (un lien en tête est le titre de la carte), ou par titre `####`	liste (`<ul class="note-cards-list">`)

Les exemples ci-dessous sont eux-mêmes des notes imbriquées : une note tabs (avec une clôture ::::) affiche la source Markdown et son rendu.

Onglets

Des contenus alternatifs, un par titre #### (ex. : par système d’exploitation).

Markdown

:::tabs
#### macOS et Linux

```bash
brew install cecilapp/tap/cecil
```

#### Windows

```bash
scoop install https://cecil.app/scoop/cecil.json
```
:::

Rendu

macOS et Linux

brew install cecilapp/tap/cecil

Windows

scoop install https://cecil.app/scoop/cecil.json

Groupe de code

Comme tabs, avec uniquement des blocs de code : sans titre, chaque bloc de code est intitulé avec son langage.

Markdown

:::code-group
```bash
curl -LO https://cecil.app/cecil.phar
```

```powershell
Invoke-WebRequest https://cecil.app/cecil.phar -OutFile cecil.phar
```
:::

Rendu

bash

curl -LO https://cecil.app/cecil.phar

powershell

Invoke-WebRequest https://cecil.app/cecil.phar -OutFile cecil.phar

Étapes

Une procédure numérotée, une étape par titre ####.

Markdown

:::steps
#### Créer un site

```bash
php cecil.phar new:site
```

#### Le prévisualiser

```bash
php cecil.phar serve
```
:::

Rendu

Créer un site
```
php cecil.phar new:site
```
Le prévisualiser
```
php cecil.phar serve
```

Accordéon

Des éléments repliables, un par titre #### (ex. : une FAQ).

Markdown

:::accordion
#### PHP est-il requis ?

Non : le binaire autonome embarque PHP.

#### Où se trouve le site généré ?

Dans le dossier `_site`.
:::

Rendu

PHP est-il requis ?

Non : le binaire autonome embarque PHP.

Où se trouve le site généré ?

Dans le dossier _site.

Cartes

Des liens vers d’autres pages, une carte par entrée de liste : un lien en tête est le titre de la carte.

Markdown

:::cards
- [Installation](../getting-started/2-installation.fr.md) : télécharger et installer Cecil.
- [Configuration](../configuration/index.fr.md) : configurer votre site.
:::

Rendu

Installation

télécharger et installer Cecil.
Configuration

configurer votre site.

Template personnalisé

Le template reçoit une variable note :

note.type : type de note (ex. : tabs)
note.id : identifiant unique dans la page (ex. : note-tabs-1)
note.content : HTML de toute la note
note.intro : HTML du contenu avant le premier titre ####
note.items : liste des éléments, chacun avec :
- title : titre (HTML)
- heading : élément titre (HTML), avec son attribut id
- id : identifiant du titre, s’il existe
- link : élément lien en tête (HTML) d’une entrée de liste
- url : URL du lien en tête d’une entrée de liste
- language : langage d’un bloc de code
- content : contenu (HTML)

Pour surcharger le rendu d’un type de note, créez le template dans votre site (ou thème), par exemple layouts/partials/notes/tip.html.twig :

<div class="callout callout-{{ note.type }}">
  {{ note.content|raw }}
</div>

Coloration syntaxique

La coloration syntaxique des blocs de code est activée par défaut avec l’option pages.body.highlight.

Si besoin, vous pouvez la désactiver avec :

pages:
  body:
    highlight: false

Exemple :

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

Est rendu en :

echo "Hello world";

Le langage d’un bloc de code est ajouté à l’attribut data-lang de l’élément <pre> (ex. : <pre data-lang="php">) : les templates par défaut l’affichent comme une étiquette.

Texte inséré

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

++text++

Est converti en :

<ins>text</ins>

Afficher en Markdown

Suggérer une modification

← Front matter Multilingue →