Cecil logo Cecil
Cecil logo Cecil
What's on this page

Markdown

Cecil supports Markdown format, but also Markdown Extra.

Cecil also provides extra features to enhance your content, see below.

Attributes

With Markdown Extra you can set an id, class and custom attributes on certain elements using an attribute block.
For instance, put the desired attribute(s) after a header, a fenced code block, a link or an image at the end of the line inside curly brackets, like this:

## Header {#id .class attribute=value}

You can create a link with the syntax [Text](url), where url can be a path, a relative path to a Markdown file, an external URL, etc.

Example:

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

Link to a page

You can easily create a link to a page with the syntax [Page title](page:page-id).

Example:

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

External

By default external links have the following value for rel attribute: noopener noreferrer.

Example:

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

You can change this behavior with pages.body.links.external options.

Cecil can try to turn a link into embedded content by using the {embed} attribute or by setting the global configuration option pages.body.links.embed.enabled to true.

Example:

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

Local video/audio files

Cecil can also create a video and audio HTML elements, through the file extension.

Example:

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

Is converted to:

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

Images

To add an image, use an exclamation mark (!) followed by alternative description in brackets ([]), and the path or URL to the image in parentheses (()).
You can optionally add a title in quotation marks.

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

Lazy loading

Cecil adds the attribute loading="lazy" to each image.

Example:

![](/image.jpg)

Is converted to:

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

Decoding

Cecil adds the attribute decoding="async" to each image.

Example:

![](/image.jpg)

Is converted to:

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

Resize

Each image in the body can be resized automatically by setting a smaller width than the original one, with the extra attribute {width=X}.

Example:

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

Is converted to:

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

Formats

If the formats option is defined, alternatives images are created and added.

Example:

![](/image.jpg)

Could be converted to:

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

Responsive

If the responsive option is enabled, then all images in the body will be made responsive automatically.

Example:

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

will be converted to:

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

The sizes attribute takes the value of the assets.images.responsive.sizes.default configuration option, but it can be changed by creating a new entry named after a class added to the image.

Example:

assets:
  images:
    responsive:
      sizes:
        default: 100vw
        my_class: "(max-width: 800px) 768px, 1024px"
![](/image.jpg){.my_class}

CSS class

You can set a default value to the class attribute of each image with the class option.

Caption

The optional title can be used to create a caption (figcaption) automatically by enabling the caption option.

Example:

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

Is converted to:

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

Localized image

For translated pages, Cecil first looks for a language-suffixed file when resolving Markdown image paths.

Example:

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

With a French page (fr), Cecil tries /images/cecil-logo.fr.png first, then falls back to /images/cecil-logo.png.

Placeholder

As images are typically heavier and slower resources, and they don’t block rendering, we should attempt to give users something to look at while they wait for the image to arrive.

The placeholder attribute accepts two options:

  1. color: display a colored background (based on image dominant color)
  2. lqip: Low-Quality Image Placeholder

Examples:

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

Table of contents

You can add a table of contents with the following Markdown syntax:

[toc]

Excerpt

An excerpt can be defined in the body with one of those following tags: excerpt or break.

Example:

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

Then use the excerpt_html filter in your template.

Notes

Create a Note block (info, tips, important, etc.).

Example:

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

Is converted to:

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

Others examples:

Syntax highlight

Code block syntax highlighting is enabled by default with the pages.body.highlight option.

If needed, you can disable it with:

pages:
  body:
    highlight: false

Example:

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

Is rendered to:

echo "Hello world";

Inserted text

Represents a range of text that has been added.

++text++

Is converted to:

<ins>text</ins>
View as Markdown
Suggest a modification
← Front matter Multilingual →