This page shows the basic Markdown rendering of the theme.

Installation

composer require cecil/theme-docs

Then add the theme to the config.yml file:

theme:
  - docs

Text formatting

Some bold, italic, strikethrough and inline code text, with a link to the guides and an external link.

A blockquote, to quote something important.

Lists

• First item
• Second item
  • Nested item
• Third item

1. Step one
2. Step two
3. Step three

Table

Image

Override a template

Create a template with the same path in your site's layouts/ folder, e.g. layouts/partials/logo.html.twig.

Colors

Primary and secondary colors are defined in assets/css/tailwind.css.

Syntax highlighting

<?php
$builder = new Cecil\Builder($config);
$builder->build(['drafts' => false]);

{% for p in site.pages.showable %}
  <a href="{{ url(p) }}">{{ p.title }}</a>
{% endfor %}

document.querySelectorAll('article h2').forEach((el) => console.log(el.id));

Mermaid

Switch the color theme to check that the diagram is re-rendered.

flowchart LR
  A[Markdown] --> B(Cecil)
  B --> C{Theme}
  C -->|light| D[HTML]
  C -->|dark| D

sequenceDiagram
  User->>Browser: Toggle theme
  Browser->>Mermaid: Re-render
  Mermaid-->>User: Diagram updated

Long page

The sections below make the page long enough to test the "On this page" table of contents and the "Back to top" button.

Section A

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Section B

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Section C

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Section D

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Is Node.js required?

No: CSS is compiled with the Tailwind standalone binary.

How to enable search?

Install the DocSearch or FlexSearch component theme.

Tags

Add a tags front matter variable to a post:

---
title: My post
tags: [release, blog]
---

Tags are displayed on the post and in the list of posts, linked to the page of each tag (e.g. /tags/release/). All tags are listed in /tags/.

Pagination

Pagination is disabled by default: enable it in the front matter of the blog section (pages/blog/index.md):

---
title: Blog
pagination:
  enabled: true
  max: 5 # number of posts by page
---

Collapsible navigation

Each sub-section of the documentation is now a collapsible group in the sidebar. Groups are open by default, and the group of the current page is always expanded. To collapse a group, add collapsed: true to the front matter of its index.md file:

---
title: Advanced
weight: 3
collapsed: true
---

Or collapse all of them at once, in the configuration:

sidebar:
  collapsed: true

Section pages also got their own template: they now display the sidebar, cards linking to their sub-pages, and the previous/next navigation.

Search without a service

Algolia DocSearch is still supported (with the DocSearch component theme), but you can now use the FlexSearch component theme instead: the search index is generated at build time, and the search runs entirely in the browser.

theme:
  - docs
  - flexsearch

Small things that matter

Some changes are less visible, but make the daily use of the theme more pleasant:

Accessibility

We also went through the theme with keyboard and screen reader users in mind:

1. A "Skip to content" link is the first focusable element of each page.
2. The mobile menu can be closed with the Escape key, and the focus is moved accordingly.
3. Current pages are announced with aria-current, and the breadcrumb is a proper navigation landmark.
4. Contrast has been improved in dark mode.

Upgrading

Update the theme with Composer, then rebuild your website:

composer update cecil/theme-docs
php cecil.phar build

Thanks to everyone who reported issues and suggested improvements. Your feedback shapes the next releases, so keep it coming!

Why a documentation theme?

Writing documentation is hard enough: the tool rendering it should get out of the way. The Docs theme was designed with a few principles in mind:

• Content first: pages are plain Markdown files, organized in folders, with no special syntax to learn.
• Navigation for free: the sidebar is built from the folders structure of pages/docs/, so adding a page is enough to make it reachable.
• Fast by default: static HTML, a single stylesheet, and JavaScript loaded only when a page needs it (Mermaid diagrams, for example).
• Readable everywhere: a responsive layout, a dark mode following the system preference, and accessible components.

Good documentation is like a good map: you only notice it when it's missing.

A blog, next to the docs

Release notes, tutorials and announcements don't always fit in the reference documentation. That's why the theme also ships templates for a blog section: create a pages/blog/ folder, add an index.md file and start writing posts.

mkdir pages/blog
cat > pages/blog/index.md <<EOF
---
title: Blog
sortby: date
---
EOF

Each post displays its date, an estimated reading time, and its author(s). Authors can be defined once in data/authors.yml, then referenced by their key in the front matter of each post:

# data/authors.yml
cecil:
  name: Cecil
  title: Static site generator
  url: https://cecil.app

# front matter of a post
---
title: Hello world
date: 2026-09-01
author: cecil
---

What's next?

In the next posts, we'll cover the new features of the theme: collapsible navigation groups, client side search, copy buttons on code blocks, and more.

In the meantime, have a look at the documentation, and feel free to open an issue on GitHub if something is missing.

Happy writing!