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
40 changes: 40 additions & 0 deletions .github/workflows/css.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
name: Check CSS

on:
push:
branches: [main]
pull_request:
workflow_dispatch:

permissions:
contents: read

concurrency:
group: css-${{ github.ref }}
cancel-in-progress: true

jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v7

- name: Install PHP
uses: shivammathur/setup-php@v2
with:
php-version: 8.3
coverage: none

- name: Install dependencies
run: composer install --no-interaction --no-progress

- name: Build CSS
run: composer css:build

- name: Check compiled CSS is up to date
run: |
if ! git diff --exit-code --stat assets/styles.css; then
echo "::error file=assets/styles.css::assets/styles.css is not up to date with its sources: run 'composer css:build' and commit the result."
exit 1
fi
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ sidebar:
collapsed: false|true # collapse the navigation groups, except the current one (default: false)
lastupdated: false|true # display the page date as "Last updated" date (default: false)
language_cookie: <name> # cookie storing the language chosen with the selector, e.g. `nf_lang` for Netlify (default: false)
inline_styles: true|false # inline the stylesheets in production: no extra request, but not cached by the browser across pages (default: true)
```

### Search
Expand Down Expand Up @@ -183,6 +184,19 @@ 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`.

### Stylesheets

A template extending the theme layouts can load additional stylesheets with the
`styles_extra` variable, set **outside of any block** (a variable set in a block
is not visible in the parent template). They are loaded before the theme stylesheet:

```twig
{% extends 'docs/page.html.twig' %}
{% set styles_extra = ['https://cdn.example.com/lib.css', 'css/custom.css'] %}
```

The `styles` block outputs additional `<head>` tags, before the theme stylesheets.

## Development

### Install deps
Expand All @@ -199,6 +213,7 @@ composer css:build

CSS is compiled with [tailwind-builder](https://github.com/ArnaudLigny/tailwind-builder),
which uses the [Tailwind](https://tailwindcss.com) standalone binary (no Node.js required).
The compiled `assets/styles.css` is committed: the CI checks it is up to date with its sources.

### Demo site

Expand Down
53 changes: 30 additions & 23 deletions assets/css/search.css
Original file line number Diff line number Diff line change
@@ -1,5 +1,33 @@
/* DocSearch */
/* should usse variables? https://github.com/algolia/docsearch/blob/df60b8ebe89c80ce3d00b80d94e95b6fd86edd19/packages/docsearch-css/src/_variables.css */
/* DocSearch (component theme) */
/* modal colors with the DocSearch variables (https://docsearch.algolia.com/docs/styling) */
/* `:root.dark` overrides the dark variables of DocSearch (`html[data-theme=dark]`) */
:root {
--docsearch-primary-color: var(--color-primary-800);
--docsearch-searchbox-focus-background: var(--color-primary-800);
--docsearch-searchbox-shadow: none;
}
:root.dark {
--docsearch-primary-color: var(--color-primary-400);
--docsearch-highlight-color: var(--docsearch-primary-color);
--docsearch-searchbox-focus-background: var(--color-primary-800);
--docsearch-modal-background: var(--color-primary-950);
--docsearch-footer-background: var(--color-primary-900);
--docsearch-hit-background: var(--color-primary-900);
--docsearch-muted-color: var(--color-secondary-300);
}
/* the highlight color is also the background of the selected hit (white text): kept dark */
.DocSearch-Hit[aria-selected=true] a {
@apply bg-primary-800 dark:bg-primary-700;
}
/* search box: light text on the dark background (no variable, the text color is used for the whole modal) */
.DocSearch-Form {
@apply text-primary-100;
}
.DocSearch-Input,
.DocSearch-Input::placeholder {
@apply text-primary-100 focus-visible:outline-hidden;
}
/* search button in the header */
.DocSearch.DocSearch-Button {
@apply w-full lg:w-48 m-0 lg:px-4 p-0;
@apply rounded-sm bg-primary-800 focus:bg-primary-700 focus:outline-hidden shadow-inner cursor-pointer;
Expand All @@ -17,27 +45,6 @@
.DocSearch-Search-Icon {
@apply text-primary-100;
}
.DocSearch-Form {
@apply text-primary-100 bg-primary-800 shadow-none;
}
.DocSearch-Input {
@apply text-primary-100 focus-visible:outline-hidden;
}
.DocSearch-Input::placeholder {
@apply text-primary-100;
}
.DocSearch-Cancel {
@apply text-primary-800;
}
.DocSearch-Hit-source {
@apply text-primary-800;
}
.DocSearch-Hit[aria-selected=true] a {
@apply bg-primary-800;
}
.DocSearch-Hits mark {
@apply text-primary-800;
}

/* FlexSearch (component theme) */
/* colors follow the `dark` class of the theme, not the system preference */
Expand Down
47 changes: 36 additions & 11 deletions assets/css/tailwind.css
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@
--color-secondary-800: var(--color-slate-800);
--color-secondary-900: var(--color-slate-900);
--color-secondary-950: var(--color-slate-950);
/* fixed header height, and scroll offset of anchors below it (also read by tocbot) */
--spacing-header: 3.5rem;
--spacing-header-offset: calc(var(--spacing-header) + 0.875rem);
}

@plugin '@tailwindcss/typography' {
Expand All @@ -38,20 +41,42 @@
@import './tocbot.css';
@import './notes.css' layer(utilities);

@utility formselect {
@apply p-1 border rounded-xs border-primary-50;
#sidebar & {
@apply border-none;
/* language selector (dropdown in the header, inline list in the sidebar) */
@utility lang-menu {
@apply relative;
& summary {
@apply flex items-center gap-1 px-2 py-1 border rounded-xs border-primary-50 cursor-pointer list-none;
}
& summary::-webkit-details-marker {
@apply hidden;
}
& .chevron {
@apply w-4 h-4 transition-transform duration-150;
}
&[open] .chevron {
@apply rotate-180;
}
& ul {
@apply absolute right-0 z-40 mt-1 min-w-full py-1 rounded-md shadow-md list-none;
@apply bg-primary-50 dark:bg-primary-950;
}
& a {
@apply block px-3 py-1 whitespace-nowrap no-underline;
@apply text-primary-950 dark:text-secondary-100 hover:bg-primary-100 dark:hover:bg-primary-900;
}
& a[aria-current] {
@apply font-semibold text-primary-700 dark:text-primary-400;
}
}

@utility selector {
@apply border-0 cursor-pointer bg-inherit text-inherit;
&:hover {
@apply text-inherit;
@utility lang-menu-inline {
& summary {
@apply px-0 border-none;
}
& ul {
@apply static mt-1 shadow-none bg-transparent dark:bg-transparent;
}
& option {
@apply bg-primary-50 dark:bg-primary-950 text-primary-950 dark:text-secondary-100;
& a {
@apply px-2 rounded-sm text-secondary-800 dark:text-secondary-300 hover:bg-primary-200 dark:hover:bg-primary-800;
}
}

Expand Down
2 changes: 1 addition & 1 deletion assets/styles.css

Large diffs are not rendered by default.

14 changes: 8 additions & 6 deletions config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,14 @@ sidebar:
collapsed: false # collapse the groups of the navigation, except the current one
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)
manifest:
background_color: '#1447E6'
theme_color: '#1447E6'
theme_color_dark: '#1C398E'
serviceworker:
enabled: false
inline_styles: true # inline the stylesheets in production (no extra request, but not cached by the browser across pages)
pwa: # PWA component theme options (`theme_color` and `theme_color_dark` are also used without it)
manifest:
background_color: '#1447E6'
theme_color: '#1447E6'
theme_color_dark: '#1C398E'
serviceworker:
enabled: false
highlightjs:
version: '11.12.0'
tocbot:
Expand Down
21 changes: 16 additions & 5 deletions layouts/_default/page.html.twig
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<!DOCTYPE html>
<html lang="{{ site.language }}" class="scroll-pt-[70px] scroll-smooth lg:overflow-y-scroll">
<html lang="{{ site.language }}" class="scroll-pt-header-offset scroll-smooth lg:overflow-y-scroll">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
Expand All @@ -15,18 +15,21 @@
{{- include('partials/metatags.html.twig') ~}}
{%- set styles = ['https://cdnjs.cloudflare.com/ajax/libs/highlight.js/' ~ site.highlightjs.version ~ '/styles/github-dark.min.css'] ~%}
{#- DocSearch component theme (https://github.com/Cecilapp/theme-docsearch) ~#}
{%- set docsearch = (site.docsearch.enabled ?? false) and site.docsearch.appId|default ~%}
{#- same condition as the component theme partials (`enabled` is set by its config: the component is installed) ~#}
{%- set docsearch = (site.docsearch.enabled ?? false) and site.docsearch.appId|default and site.docsearch.apiKey|default and site.docsearch.indexName|default ~%}
{%- if docsearch ~%}
{{- include('partials/docsearch/head.html.twig', ignore_missing = true) ~}}
{%- elseif site.flexsearch.enabled ?? false ~%}
{#- FlexSearch component theme (https://github.com/Cecilapp/theme-flexsearch) ~#}
{%- set styles = styles|merge(['flexsearch/flexsearch.css']) ~%}
{%- endif ~%}
{#- additional <head> tags, output before the theme stylesheets (to add a stylesheet to them, use `styles_extra`: a variable set in a block is not visible here) ~#}
{%- block styles %}{% endblock ~%}
{%- set styles = styles|merge(['styles.css']) ~%}
{#- stylesheets added by a child template, kept out of the main bundle (`styles_extra` must be set outside of any block) and loaded before it so the theme can override them ~#}
{%- set styles_extra = styles_extra ?? [] ~%}
{%- if getenv('CECIL_ENV') == 'production' ~%}
{#- in production, stylesheets are inlined (no extra request, but not cached across pages), unless `inline_styles` is disabled ~#}
{%- if getenv('CECIL_ENV') == 'production' and (site.inline_styles ?? true) ~%}
{%- for style in styles_extra ~%}
<style>{{ asset(style)|inline }}</style>
{%- endfor ~%}
Expand All @@ -37,6 +40,14 @@
{%- endfor ~%}
{{ html(asset(styles)) }}
{%- endif ~%}
{#- browser UI color, set by the PWA component theme if installed (it generates the `manifest` page) ~#}
{%- set manifest = site.pwa.manifest ?? {} ~%}
{%- if (site.page('manifest') ?? null) is null and manifest.theme_color|default ~%}
<meta name="theme-color" content="{{ manifest.theme_color }}"{% if manifest.theme_color_dark|default %} media="(prefers-color-scheme: light)"{% endif %}>
{%- if manifest.theme_color_dark|default ~%}
<meta name="theme-color" content="{{ manifest.theme_color_dark }}" media="(prefers-color-scheme: dark)">
{%- endif ~%}
{%- endif ~%}
{{- include('partials/pwa.html.twig', {site}, with_context = false, ignore_missing: true) ~}}
</head>
<body class="font-sans antialiased bg-primary-50 dark:bg-primary-950 text-[#050505] dark:text-secondary-100">
Expand All @@ -53,7 +64,7 @@
{%- block sidebar ~%}
{%- embed 'partials/sidebar.html.twig' with {'showlarge': false} %}{% endembed ~%}
{%- endblock sidebar ~%}
<header class="fixed top-0 inset-x-0 z-30 flex items-center h-14 bg-primary-700 dark:bg-primary-900 shadow-md">
<header class="fixed top-0 inset-x-0 z-30 flex items-center h-header bg-primary-700 dark:bg-primary-900 shadow-md">
<nav class="flex items-center w-full px-4">
{#- sidebar mobile button ~#}
<button id="sidebar-open-button" type="button" class="navbar-item flex lg:hidden items-center mr-3 cursor-pointer" onclick="toggleMenu()" aria-controls="sidebar" aria-expanded="false" aria-label="{% trans %}Open menu{% endtrans %}" title="{% trans %}Open menu{% endtrans %}">
Expand Down Expand Up @@ -102,7 +113,7 @@
{%- endif ~%}
</nav>
</header>
<main id="main" tabindex="-1" class="h-full mt-14 focus:outline-none">
<main id="main" tabindex="-1" class="h-full mt-header focus:outline-none">
{%- block article ~%}
<div class="container mx-auto px-4 py-6">
{{- include('partials/breadcrumb.html.twig') ~}}
Expand Down
12 changes: 2 additions & 10 deletions layouts/docs/list.html.twig
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,10 @@

{#- sub-sections and pages of the section ~#}
{%- block after_content ~%}
{%- set children = [] ~%}
{%- for s in page.sections ~%}
{%- set children = children|merge([s]) ~%}
{%- endfor ~%}
{%- for p in page.pages.showable ~%}
{%- if p.type != 'section' and p.parent and p.parent.id == page.id ~%}
{%- set children = children|merge([p]) ~%}
{%- endif ~%}
{%- endfor ~%}
{%- set children = page.sections|merge(page.pages.showable|filter(p => p.type != 'section' and p.parent and p.parent.id == page.id))|sort_by_weight ~%}
{%- if children is not empty ~%}
<nav class="mt-6 grid grid-cols-1 md:grid-cols-2 gap-4" aria-label="{{ page.title }}">
{%- for child in children|sort_by_weight ~%}
{%- for child in children ~%}
<a href="{{ url(child) }}" class="block px-5 py-4 rounded-xl border border-secondary-200 dark:border-secondary-700 shadow-md hover:border-primary-700 dark:hover:border-primary-400 hover:no-underline text-inherit dark:text-inherit">
<h2 class="font-semibold text-lg mb-1">{{ child.title }}</h2>
{%- if child.description|default ~%}
Expand Down
57 changes: 32 additions & 25 deletions layouts/docs/page.html.twig
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
{% extends '_default/page.html.twig' %}

{% set styles_extra = ['https://cdnjs.cloudflare.com/ajax/libs/tocbot/' ~ site.tocbot.version ~ '/tocbot.min.css'] %}
{#- "On this page" ToC (set outside of any block to be visible in all of them) ~#}
{% set toc = page.body|toc %}
{% set has_toc = toc|striptags|trim is not empty %}
{#- tocbot is loaded only if the page has a ToC; merged with the stylesheets of a template extending this one ~#}
{% set styles_extra = (has_toc ? ['https://cdnjs.cloudflare.com/ajax/libs/tocbot/' ~ site.tocbot.version ~ '/tocbot.min.css'] : [])|merge(styles_extra ?? []) %}

{%- block sidebar ~%}
{%- embed 'partials/sidebar.html.twig' with {'showlarge': true} ~%}
Expand All @@ -19,8 +23,6 @@
<div class="grow mx-auto max-w-3xl">
{{- include('partials/breadcrumb.html.twig') ~}}
{#- "On this page" ~#}
{%- set toc = page.body|toc ~%}
{%- set has_toc = toc|striptags|trim is not empty ~%}
{%- if has_toc ~%}
<details class="mb-4 xl:hidden rounded-md bg-primary-100 dark:bg-primary-900 px-2 py-1">
<summary class="cursor-pointer text-sm uppercase text-secondary-600 dark:text-secondary-300">
Expand All @@ -44,7 +46,7 @@
</div>
{#- "On this page" ToC ~#}
<div>
<aside id="on-this-page" class="hidden xl:block py-6 w-64 text-secondary-500 dark:text-secondary-300 sticky top-20">
<aside id="on-this-page" class="hidden xl:block py-6 w-64 text-secondary-500 dark:text-secondary-300 sticky top-[calc(var(--spacing-header)+--spacing(6))]">
{%- if has_toc ~%}
<nav class="pb-4 mb-5 border-b border-secondary-400 dark:border-secondary-500">
<div class="flex space-x-2 items-center mb-2 font-semibold text-sm uppercase tracking-wider">
Expand All @@ -70,30 +72,35 @@

{%- block scripts ~%}
{{- parent() ~}}
{%- if has_toc ~%}
{{- html(asset('https://cdnjs.cloudflare.com/ajax/libs/tocbot/' ~ site.tocbot.version ~ '/tocbot.min.js', {minify: false})) ~}}
<script>{% apply minify_js ~%}
{# toc #}
if (document.getElementById('on-this-page-toc')) tocbot.init({
tocSelector: '#on-this-page-toc',
contentSelector: '#content',
headingSelector: 'h2, h3',
hasInnerContainers: true,
scrollSmooth: false,
headingsOffset: 70,
scrollSmoothOffset: -70,
});
{# article anchor #}
window.addEventListener('load', function (e) {
const allHx = document.querySelectorAll('article h2[id], article h3[id]');
allHx.forEach((item) => {
let anchor = document.createElement('a');
anchor.href = '#' + item.getAttribute('id');
anchor.innerText = '#';
anchor.className = 'anchor-title';
anchor.setAttribute('aria-label', '{{ 'Permalink to this section'|trans|e('js') }}');
anchor.title = anchor.getAttribute('aria-label');
item.append(anchor);
{# toc (offset: scroll padding of the fixed header) #}
(function () {
const offset = parseFloat(getComputedStyle(document.documentElement).scrollPaddingTop) || 0;
tocbot.init({
tocSelector: '#on-this-page-toc',
contentSelector: '#content',
headingSelector: 'h2, h3',
hasInnerContainers: true,
collapseDepth: 3, {# all levels expanded #}
scrollSmooth: false,
headingsOffset: offset,
scrollSmoothOffset: -offset,
});
})();
{% endapply %}</script>
{%- endif ~%}
<script>{% apply minify_js ~%}
{# article anchors (after the ToC init, so they are not part of its entries; the content is already parsed) #}
document.querySelectorAll('article h2[id], article h3[id]').forEach((item) => {
const anchor = document.createElement('a');
anchor.href = '#' + item.getAttribute('id');
anchor.innerText = '#';
anchor.className = 'anchor-title';
anchor.setAttribute('aria-label', '{{ 'Permalink to this section'|trans|e('js') }}');
anchor.title = anchor.getAttribute('aria-label');
item.append(anchor);
});
{% endapply %}</script>
{#- mermaid (loaded only if the page contains a diagram) ~#}
Expand Down
Loading
Loading