Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 43 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ _Docs_ is a documentation theme for [Cecil](https://cecil.app), designed to prov
- Templates internationalization (i18n)
- Mobile friendly
- Dark theme
- Blog posts templates
- Blog posts templates, with tags, pagination and feed link
- Documentation versions selector

## Installation

Expand Down Expand Up @@ -69,6 +70,21 @@ language_cookie: <name> # cookie storing the language chosen with the selector,
inline_styles: true|false # inline the stylesheets in production: no extra request, but not cached by the browser across pages (default: true)
```

### Versions

To publish several versions of the documentation (e.g. one deployment per
version), list them in the `versions` option: they are displayed in a selector,
next to the site title.

```yaml
versions:
- name: '2.x'
url: https://docs.example.com/
- name: '1.x'
url: https://v1.docs.example.com/
version: '2.x' # name of the current version (default: the first one)
```

### Search

The search button is displayed in the header, with one of the following
Expand Down Expand Up @@ -184,6 +200,32 @@ Posts of the `blog` section display their date, reading time and author(s):
`author` (or `authors`) front matter variable, as an object (`name`, `title`,
`url`, `email`, `image`) or as a key of `data/authors.yml`.

Posts can be tagged with the `tags` front matter variable: tags are linked to
their page (e.g. `/tags/release/`), and all of them are listed in `/tags/`.

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

The list of posts links to its feed, and can be paginated: pagination is
disabled by default, enable it in the front matter of the blog section
(`pages/blog/index.md`).

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

> [!NOTE]
> Enabling the pagination of a single section requires Cecil X.Y or later.

### Stylesheets

A template extending the theme layouts can load additional stylesheets with the
Expand Down
18 changes: 15 additions & 3 deletions assets/css/tailwind.css
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,8 @@
@import './tocbot.css';
@import './notes.css' layer(utilities);

/* language selector (dropdown in the header, inline list in the sidebar) */
@utility lang-menu {
/* dropdown of links: language and version selectors (in the header, or inline list in the sidebar) */
@utility dropdown {
@apply relative;
& summary {
@apply flex items-center gap-1 px-2 py-1 border rounded-xs border-primary-50 cursor-pointer list-none;
Expand All @@ -68,7 +68,7 @@
@apply font-semibold text-primary-700 dark:text-primary-400;
}
}
@utility lang-menu-inline {
@utility dropdown-inline {
& summary {
@apply px-0 border-none;
}
Expand All @@ -79,6 +79,18 @@
@apply px-2 rounded-sm text-secondary-800 dark:text-secondary-300 hover:bg-primary-200 dark:hover:bg-primary-800;
}
}
/* dropdown aligned on its start (e.g. next to the logo) */
@utility dropdown-start {
& ul {
@apply left-0 right-auto;
}
}

/* tags (links to the terms pages) */
@utility tag {
@apply inline-block px-2 py-0.5 rounded-full text-sm no-underline;
@apply bg-primary-100 dark:bg-primary-900 text-primary-700 dark:text-primary-300 hover:bg-primary-200 dark:hover:bg-primary-800;
}

@layer base {
/* links */
Expand Down
2 changes: 1 addition & 1 deletion assets/styles.css

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
"extra": {
"name": "docs",
"branch-alias": {
"dev-main": "2.x-dev"
"dev-main": "6.x-dev"
}
},
"minimum-stability": "dev",
Expand Down
10 changes: 9 additions & 1 deletion config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,12 @@ sidebar:
language_cookie: false # name of a cookie storing the language chosen with the selector (e.g. `nf_lang` for Netlify redirects)
lastupdated: false # display the page date as "Last updated on" (the `updated` front matter variable is always displayed)
inline_styles: true # inline the stylesheets in production (no extra request, but not cached by the browser across pages)
#versions: # documentation versions, displayed in a selector of the header (e.g. other deployments)
# - name: '2.x'
# url: https://example.com/
# - name: '1.x'
# url: https://v1.example.com/
#version: '2.x' # name of the current version (default: the first one)
pwa: # PWA component theme options (`theme_color` and `theme_color_dark` are also used without it)
manifest:
background_color: '#1447E6'
Expand All @@ -23,9 +29,11 @@ mermaid:
version: '11.17.2'

# Cecil config for Docs
taxonomies:
tags: tag # `tags` front matter variable (e.g. blog posts), listed in `/tags/`
pages:
pagination:
enabled: false
enabled: false # enable it in the front matter of a list page (e.g. the blog): `pagination: {enabled: true}`
sortby: weight
body:
highlight:
Expand Down
6 changes: 6 additions & 0 deletions demo/cecil.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ baseurl: http://localhost:8000/
author:
name: Cecil
url: https://cecil.app
# documentation versions (selector in the header)
versions:
- name: main
url: /
- name: '5.0'
url: https://github.com/Cecilapp/theme-docs/tree/5.0.0
# `themes/docs` links to the root of this repository (see `link.php`)
theme:
- docs
Expand Down
1 change: 1 addition & 0 deletions demo/pages/blog/2026-09-01-hello-world.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Hello world
description: "Welcome to the blog of the _Docs_ theme! This first post introduces the theme, explains why it exists, and shows how a blog can live next to your documentation in the same Cecil website."
date: 2026-09-01
author: cecil
tags: [announcement, blog]
---
Welcome to the blog of the _Docs_ theme! This first post introduces the theme, explains why it exists, and shows how a blog can live next to your documentation in the same Cecil website.

Expand Down
1 change: 1 addition & 0 deletions demo/pages/blog/2026-10-01-new-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
title: New release
description: "Collapsible navigation, search without a service, copy buttons and accessibility improvements: a tour of the new version of the theme."
date: 2026-10-01
tags: [release, accessibility]
authors:
- cecil
- name: Jane Doe
Expand Down
34 changes: 34 additions & 0 deletions demo/pages/blog/2026-10-15-tags-and-pagination.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: Tags and pagination
description: "Blog posts can be tagged, and the blog can be paginated: how to use these two features of the theme."
date: 2026-10-15
author: cecil
tags: [blog, release]
---
Blog posts can now be tagged, and the list of posts can be paginated.

## Tags

Add a `tags` front matter variable to a post:

```yaml
---
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`):

```yaml
---
title: Blog
pagination:
enabled: true
max: 5 # number of posts by page
---
```
3 changes: 3 additions & 0 deletions demo/pages/blog/index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
---
title: Blog
sortby: date
pagination:
enabled: true # pagination is disabled by default, except for the pages enabling it
max: 2
---
News about the Docs theme.
Binary file modified docs/screenshot.dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/screenshot.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion layouts/_default/list.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
<div class="py-6">
<nav class="grid grid-cols-1 md:grid-cols-2 gap-8">
{%- for p in pages ~%}
<section class="px-6 py-6 rounded-xl border border-secondary-200 shadow-md hover:border-primary-700 dark:hover:border-primary-400 h-full">
<section class="px-6 py-6 rounded-xl border border-secondary-200 dark:border-secondary-700 shadow-md hover:border-primary-700 dark:hover:border-primary-400 h-full">
{%- if p.parent and p.parent.parent ~%}
<a href="{{ url(p.parent) }}"><div class="text-sm mb-2">{{ p.parent.title }}</div></a>
{%- endif ~%}
Expand Down
23 changes: 23 additions & 0 deletions layouts/_default/page.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,12 @@
</button>
{#- logo ~#}
{{- include('partials/logo.html.twig') ~}}
{#- version selector ~#}
{%- if site.versions|default ~%}
<div class="navbar-item ml-3 hidden sm:flex">
{{- include('partials/selector-version.html.twig') ~}}
</div>
{%- endif ~%}
<div class="grow"></div>
{#- main menu ~#}
<div class="hidden lg:flex ml-4 items-center">
Expand Down Expand Up @@ -132,6 +138,23 @@
</a>
</div>
<script>{% apply minify_js ~%}
{# dropdowns (language and version selectors): closed on outside click or Escape key #}
(function () {
function closeDropdowns(except) {
document.querySelectorAll('.dropdown[open]').forEach(function (dropdown) {
if (dropdown !== except) dropdown.open = false;
});
}
document.addEventListener('click', function (e) {
closeDropdowns(e.target.closest('.dropdown'));
});
document.addEventListener('keydown', function (e) {
if (e.key !== 'Escape') return;
const dropdown = document.activeElement && document.activeElement.closest('.dropdown[open]');
closeDropdowns();
if (dropdown) dropdown.querySelector('summary').focus();
});
})();
{# scroll top #}
(function () {
const buttonTop = document.getElementById('button-top');
Expand Down
10 changes: 10 additions & 0 deletions layouts/_default/term.html.twig
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{#- pages of a term (e.g. a tag), listed like blog posts ~#}
{% extends 'blog/list.html.twig' %}

{%- block content ~%}
<h1>{% if page.plural == 'tags' %}#{% endif %}{{ page.title }}</h1>
{%- set vocabulary = site.page(page.plural) ~%}
{%- if vocabulary ~%}
<p><a href="{{ url(vocabulary) }}">{% trans %}All tags{% endtrans %}</a></p>
{%- endif ~%}
{%- endblock content ~%}
11 changes: 11 additions & 0 deletions layouts/_default/vocabulary.html.twig
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{#- terms of a vocabulary (e.g. all tags), with their number of pages ~#}
{% extends '_default/page.html.twig' %}

{%- block content ~%}
<h1>{{ page.title }}</h1>
<ul class="not-markdown flex flex-wrap gap-2 list-none p-0">
{%- for term in page.terms ~%}
<li><a href="{{ url(term.id, {language: site.language}) }}" class="tag">{% if page.plural == 'tags' %}#{% endif %}{{ term.name }} <span class="opacity-75">({{ term|length }})</span></a></li>
{%- endfor ~%}
</ul>
{%- endblock content ~%}
36 changes: 25 additions & 11 deletions layouts/blog/list.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,34 @@
{%- if page.content %}{{ page.content }}{% endif ~%}
{%- endblock content ~%}
</section>
{#- feed link ~#}
{%- for alternate in page.alternates|default([]) ~%}
{%- if alternate.format in ['atom', 'rss'] ~%}
<a href="{{ url(page, {format: alternate.format}) }}" type="{{ alternate.type }}" class="mt-2 inline-flex items-center gap-1 text-sm">
<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-4 h-4" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" d="M12.75 19.5v-.75a7.5 7.5 0 0 0-7.5-7.5H4.5m0-6.75h.75c7.87 0 14.25 6.38 14.25 14.25v.75M6 18.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0Z" /></svg>
{%- trans %}Subscribe to the feed{% endtrans ~%}
</a>
{%- endif ~%}
{%- endfor ~%}
<div class="py-6">
<nav class="grid grid-cols-1 gap-8">
<div class="grid grid-cols-1 gap-8">
{%- for p in pages ~%}
<a href="{{ url(p) }}" class="hover:no-underline text-inherit dark:text-inherit">
<section class="px-6 py-6 rounded-xl border border-secondary-200 shadow-md hover:border-primary-700 dark:hover:border-primary-400 h-full">
<div class="text-sm">{{ p.date|format_date('long') }}</div>
<h2 class="mt-1 font-semibold text-lg">{{ p.title }}</h2>
{#- description from front matter, or excerpt of the content ~#}
<div class="mt-2 text-secondary-600 dark:text-secondary-400 font-normal">{{ p.description is defined and p.description is not empty ? p.description : p.content|excerpt_html }}</div>
</section>
</a>
{#- the whole card is clickable (stretched title link), tags are above it ~#}
<article class="relative px-6 py-6 rounded-xl border border-secondary-200 dark:border-secondary-700 shadow-md hover:border-primary-700 dark:hover:border-primary-400 h-full">
<div class="text-sm"><time datetime="{{ p.date|date('c') }}">{{ p.date|format_date('long') }}</time></div>
<h2 class="mt-1 font-semibold text-lg"><a href="{{ url(p) }}" class="hover:no-underline text-inherit dark:text-inherit after:absolute after:inset-0">{{ p.title }}</a></h2>
{#- description from front matter, or excerpt of the content ~#}
<div class="mt-2 text-secondary-600 dark:text-secondary-400 font-normal">{{ p.description is defined and p.description is not empty ? p.description : p.content|excerpt_html }}</div>
{%- if p.tags|default ~%}
<div class="mt-3">
{{- include('partials/tags.html.twig', {p: p}) ~}}
</div>
{%- endif ~%}
</article>
{%- endfor ~%}
</nav>
</div>
{{- include('partials/paginator.html.twig') ~}}
</div>
</div>
</div>
{%- endblock article ~%}
{%- endblock article ~%}
5 changes: 5 additions & 0 deletions layouts/blog/page.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,11 @@
{%- endfor ~%}
</div>
{%- endif ~%}
{%- if page.tags|default ~%}
<div class="mt-3 not-markdown">
{{- include('partials/tags.html.twig') ~}}
</div>
{%- endif ~%}
</header>
{{ page.content }}
<footer class="mt-6">
Expand Down
7 changes: 6 additions & 1 deletion layouts/docs/page.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,13 @@
{%- block sidebar ~%}
{%- embed 'partials/sidebar.html.twig' with {'showlarge': true} ~%}
{%- block navigation ~%}
{%- set docs = site.page('docs') ~%}
<div class="py-2 mt-2">
{{- include('partials/sidebar-nav.html.twig', {'section': site.page('docs')}) ~}}
{#- home page of the documentation ~#}
<ol>
<li><a href="{{ url(docs) }}" class="flex{% if docs.id == page.id %} active{% endif %}"{% if docs.id == page.id %} aria-current="page"{% endif %}>{{ docs.title }}</a></li>
</ol>
{{- include('partials/sidebar-nav.html.twig', {'section': docs}) ~}}
</div>
{%- endblock navigation ~%}
{%- endembed ~%}
Expand Down
17 changes: 17 additions & 0 deletions layouts/partials/paginator.html.twig
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{#- pagination of a list page (`pagination` front matter variable) ~#}
{%- if page.paginator.count|default(0) > 1 ~%}
{%- set links = page.paginator.links ~%}
<nav class="mt-6 flex items-center justify-between gap-4" aria-label="{% trans %}Pagination{% endtrans %}">
{%- if links.prev is defined ~%}
<a href="{{ url(links.prev) }}" rel="prev" class="py-2 px-4 font-medium hover:no-underline border border-secondary-300 hover:border-primary-700 dark:hover:border-primary-400 rounded-md">← {% trans %}Previous{% endtrans %}</a>
{%- else ~%}
<span></span>
{%- endif ~%}
<span class="text-sm text-secondary-600 dark:text-secondary-300">{% trans with {'%current%': page.paginator.current, '%count%': page.paginator.count} %}Page %current% of %count%{% endtrans %}</span>
{%- if links.next is defined ~%}
<a href="{{ url(links.next) }}" rel="next" class="py-2 px-4 font-medium hover:no-underline border border-secondary-300 hover:border-primary-700 dark:hover:border-primary-400 rounded-md">{% trans %}Next{% endtrans %} →</a>
{%- else ~%}
<span></span>
{%- endif ~%}
</nav>
{%- endif ~%}
Loading
Loading