Paper theme

The Paper theme for Cecil is a minimal, responsive, accessible and SEO-friendly blog theme, ported from AstroPaper by Sat Naing.

Demo

Features

• Minimal, responsive and accessible design (keyboard navigation, skip link, ARIA labels)
• Light and dark color schemes, with the dark mode toggle component theme
• SEO-friendly: Cecil built-in metatags (Open Graph, Twitter cards, JSON-LD BlogPosting), sitemap and Atom feeds
• Dynamic Open Graph images, generated for each post (title, author and site title)
• Featured and recent posts on the homepage
• Paginated posts list, tags, archives (by year and month)
• Posts: reading progress bar, "Go back" and "Back to top" buttons, previous and next posts, share links, "Edit page" link, collapsible table of contents, copy button on code blocks, images lightbox
• Callouts (:::note, :::tip, :::important, :::warning, :::caution…) and Cecil notes (steps, accordion, tabs, cards)
• Optional search with the FlexSearch component theme
• Translatable (English and French included)

Requirements

• Cecil 9.25 or later, with plugins support: the theme extensions are registered by the Paper\PaperPlugin plugin
• PHP GD extension with FreeType support, to generate the Open Graph images

Installation

Allow the theme installer plugin in the composer.json file of your Cecil project (required since Composer 2.2):

{
  "config": {
    "allow-plugins": {
      "cecil/theme-installer": true
    }
  }
}

Then require the theme:

composer require cecil/theme-paper

Or download the latest archive and uncompress its content in themes/paper, together with the darkmodetoggle theme in themes/darkmodetoggle.

Usage

Add paper and darkmodetoggle in the theme section of your configuration file (cecil.yml):

theme:
  - paper
  - darkmodetoggle

Write your posts in pages/posts/, and disable the pagination of the homepage in pages/index.md (its content is the introduction of the homepage):

---
title: Hello
pagination: false
---
Welcome to my blog.

Front matter of posts

Variable	Description
title	Title of the post
description	Description, used in the posts lists and the meta tags
date	Publication date
updated	Modification date (displayed when more recent than date)
author	Author (site author by default)
tags	Tags
featured	Displays the post in the Featured section of the homepage
draft	Unpublishes the post
image	Open Graph image (otherwise an image is generated)
hide_edit	Hides the Edit page link

Add [toc] in the body of a post to display a collapsible table of contents.

Search

Install the FlexSearch component theme to display a search button in the header:

composer require cecil/theme-flexsearch

theme:
  - flexsearch
  - paper
  - darkmodetoggle

Configuration

Options and their 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/ (empty to disable)
  og:
    dynamic: true  # generates Open Graph images of posts (and of the site) without image
  socials: []      # social links: [{name: github, url: 'https://github.com/username'}]
  share:           # share links of posts (`false` to disable)
    - {name: whatsapp, url: 'https://wa.me/?text='}
    - {name: facebook, url: 'https://www.facebook.com/sharer.php?u='}
    - {name: x, url: 'https://x.com/intent/post?url='}
    - {name: telegram, url: 'https://t.me/share/url?url='}
    - {name: pinterest, url: 'https://pinterest.com/pin/create/button/?url='}
    - {name: mail, url: 'mailto:?subject=See%20this%20post&body='}

Icons available for social and share links: github, x, linkedin, facebook, telegram, whatsapp, pinterest and mail (add your own in assets/paper/icons/<name>.svg).

The theme also sets these Cecil options:

taxonomies:
  tags: tag
menus:
  main: # the header menu (the homepage entry is not displayed)
    - {id: index, enabled: false}
    - {id: posts, name: Posts, url: posts, weight: 10}
    - {id: tags, name: Tags, url: tags, weight: 20}
pages:
  pagination:
    max: 4 # posts per page
  default:
    archives: # the archives page (`published: false` to disable it)
      path: archives
      layout: archives
metatags:
  articles: posts

[!NOTE] A menus.main list defined by the site replaces the theme one: declare the Posts and Tags entries again.

If the posts section is not posts, set paper.posts.section, metatags.articles, and map the section to the posts layouts:

layouts:
  sections:
    blog: posts

Open Graph images

When a post has no image, an Open Graph image (1200 × 628) is generated with its title, author and the site title, and published next to the post (og.png). Other pages use an image of the site (title and description) when the image option of the site is not set.

It requires the PHP GD extension with FreeType support. The background (assets/paper/og-background.png) and the fonts (assets/paper/fonts/) can be overridden by the site.

Colors

Override the CSS custom properties in a stylesheet of the site (extend the head_css block of page.html.twig):

: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 family can be changed with --paper-font.

Internationalization

The theme is translated in English and French (translations/messages.fr.yml). Add your own translations in the translations/ directory of the site.

Development

Styles are built with Tailwind CSS (assets/paper/tailwind.css → assets/paper/paper.css):

composer install
composer css:build # or css:watch

Run the demo site:

composer install --working-dir=demo # dark mode toggle and FlexSearch themes
php demo/link.php
php cecil.phar serve demo

Extensions

The PHP classes of the theme live in extensions/Paper/ (Paper namespace), and are registered by the Paper\PaperPlugin plugin, declared in config.yml:

extensions:
  plugins:
    Paper: Paper\PaperPlugin

Class	Role
Paper\PaperPlugin	Registers the extensions of the theme
Paper\Twig\PaperExtension	paper_group_by_date filter and paper_og_image function (Twig)

A site can disable or replace an extension by its name, e.g. layouts: {extensions: {PaperExtension: false}}.

Credits

• AstroPaper by Sat Naing (MIT)
• Google Sans Code font (SIL Open Font License)
• Tabler Icons (MIT)

License

Paper is a free software distributed under the terms of the MIT license.