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!