Introduction

Writing a post is enough: if the post has no image in its front matter, the Paper theme generates an Open Graph image (1200 × 628 pixels) with:

• the title of the post
• its author
• the title of the site

The image is published next to the post (e.g.: /posts/dynamic-og-images/og.png) and referenced by the built-in Cecil metatags. Other pages share an image generated with the title and the description of the site (/og.png), unless the site image option is set.

Requirements

Images are generated with the PHP GD extension, compiled with FreeType support. Without it, the default metatags behavior is used.

Customization

• The background of the image is assets/paper/og-background.png: override it with your own assets/paper/og-background.png (1200 × 628 pixels).
• The fonts are assets/paper/fonts/GoogleSansCode-Regular.ttf and assets/paper/fonts/GoogleSansCode-Bold.ttf.
• Disable the generation with the paper.og.dynamic option:

paper:
  og:
    dynamic: false

Use the image front matter variable to define the image of a post:

---
title: My post
image: /images/my-post.png
---

Creating a blog post

To write a new blog post, create a Markdown file inside the pages/posts/ directory.

pages/
└── posts/
    ├── _drafts/
    │   └── an-unfinished-post.md
    ├── 2026/
    │   └── example-post.md
    └── adding-new-post.md

The post URL is built from its file name (or its slug): pages/posts/adding-new-post.md is published at /posts/adding-new-post/.

Front matter

The front matter is the YAML block at the top of the post:

Sample front matter:

---
title: The title of the post
description: Some description about the post.
date: 2026-09-25T04:58:53Z
updated: 2026-10-10T12:00:00Z
author: Your Name
featured: true
tags:
  - some
  - example
  - tags
---

Table of contents

Add [toc] where the table of contents should be displayed (h2 and h3 headings by default).

Headings

There's one thing to note about headings: the post title is the main heading (h1), so the rest of the headings should start from h2.

Callouts

Callouts are Cecil notes:

:::tip
Helpful advice, shortcuts, or best practices.
:::

Steps and accordions

Cecil provides more notes types, such as steps:

And accordions:

Code blocks

Code blocks are highlighted at build time, and a copy button is added:

<?php
$builder = new Cecil\Builder($config);
$builder->build();

Images

Images are stored in the assets/ directory, then referenced with an absolute path:

![A picture of the Paper theme](/images/paper.png)

Click on an image to zoom it.

Footnotes

Footnotes are supported¹.

Install the theme

Allow the theme installer plugin, then require the theme with Composer:

composer require cecil/theme-paper

The dark mode toggle component theme is installed as a dependency. Declare both themes in the configuration file (cecil.yml):

theme:
  - paper
  - darkmodetoggle

Site metadata

Paper relies on the standard Cecil configuration for the site metadata, used by the built-in metatags (title, description, Open Graph, Twitter cards, JSON-LD) and by the feeds:

title: Paper
description: A minimal, responsive and SEO-friendly Cecil blog theme.
baseurl: https://example.com/
author:
  name: Your Name
  url: https://example.com/about/
language: en

Theme options

All the options are namespaced under paper, with these default values:

paper:
  posts:
    section: posts # section containing the blog posts
    home: 4        # number of recent posts displayed on the homepage
  dir: ltr         # text direction: ltr or rtl
  archives: true   # displays the archives link in the header
  back_button: true # displays the "Go back" button on posts
  edit:
    url: ''        # e.g.: https://github.com/<user>/<repo>/edit/main/pages/
  og:
    dynamic: true  # generates Open Graph images of posts without `image`

The number of posts per page is the Cecil pagination option (4 by default with Paper):

pages:
  pagination:
    max: 4

Menu

The header menu is the Cecil main menu. Paper defines the Posts and Tags entries, add your own entries (or pages with menu: main in their front matter):

menus:
  main:
    - {id: about, name: About, url: about, weight: 30}

The archives link, the search button (with FlexSearch) and the light/dark toggle are always displayed after the menu entries.

Social links

Social links are displayed in the footer and on the homepage:

paper:
  socials:
    - {name: github, url: 'https://github.com/username'}
    - {name: x, url: 'https://x.com/username'}
    - {name: linkedin, url: 'https://www.linkedin.com/in/username/'}
    - {name: mail, url: 'mailto:yourmail@example.com'}

Available icons are github, x, linkedin, facebook, telegram, whatsapp, pinterest and mail. Add your own SVG icons in assets/paper/icons/<name>.svg. The link title can be customized with the title key.

Share links

Posts display share links (WhatsApp, Facebook, X, Telegram, Pinterest and email by default). Customize them, or disable them with false:

paper:
  share:
    - {name: x, url: 'https://x.com/intent/post?url='}
    - {name: mail, url: 'mailto:?subject=See%20this%20post&body='}

Edit page link

Set the URL of your repository to display an Edit page link on posts, followed by the path of the Markdown file relative to the pages directory:

paper:
  edit:
    url: https://github.com/username/repository/edit/main/pages/

Hide it on a post with hide_edit: true in the front matter.

Colors

Colors are CSS custom properties: override them in a stylesheet of your site, loaded after the theme one (extend the head_css block of the page.html.twig layout):

:root,
[data-theme='light'] {
  --background: #fdfdfd;
  --foreground: #282728;
  --accent: #006cac;
  --accent-foreground: #ffffff;
  --muted: #e6e6e6;
  --muted-foreground: #6b7280;
  --border: #ece9e9;
}

[data-theme='dark'] {
  --background: #212737;
  --foreground: #eaedf3;
  --accent: #ff6b01;
  --accent-foreground: #ffffff;
  --muted: #343f60;
  --muted-foreground: #afb9ca;
  --border: #ab4b08;
}

The font can be changed with the --paper-font custom property.