How to configure the Paper theme

This guide covers the available configuration options of the Paper theme, a port of AstroPaper for Cecil.

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.