Skip to content

Lighter navigation and assets, accessibility, header height variable, inline_styles option and CSS check - #4

Merged
ArnaudLigny merged 13 commits into
fix/review-improvementsfrom
refactor/review-follow-up
Oct 20, 2026
Merged

ArnaudLigny merged 13 commits into
fix/review-improvementsfrom
refactor/review-follow-up

Conversation

@ArnaudLigny

@ArnaudLigny ArnaudLigny commented Oct 20, 2026 •

Copy link
Copy Markdown
Member

Stacked on #3: merge it first (this PR will then target main).

Changes

Navigation and assets

  • Navigation: the children of a section (sub-sections and pages) are computed in a single merge/filter/sort_by_weight expression instead of merging an array at each iteration; the ancestors ids of the current page are computed once for the whole sidebar.
  • tocbot: stylesheet and script loaded only if the page has a ToC (computed once, outside of any block).
  • "On this page" ToC: all levels expanded (collapseDepth: 3), nested headings are no longer collapsed until their section is active.
  • Heading anchors: added as soon as the script runs, instead of waiting for all images to be loaded (load event).

Accessibility

  • Language selector: the <select onchange> (navigation on change is not accessible, WCAG 3.2.2) is replaced by a <details> dropdown of links (hreflang, lang, current language marked with aria-current), closed on outside click or Escape key (focus back on its button); inline list in the mobile sidebar. The language_cookie option still works.
  • Theme toggle: "Dark theme" toggle button with aria-pressed (was "Change theme color", without state). French translation updated (.po and .mo).

Layouts

  • DocSearch modal colors: set with the DocSearch CSS variables instead of overriding its classes; in the dark theme, the highlight color (hit source, matches, cancel button) is now readable and the backgrounds follow the theme palette.
  • DocSearch: the theme now uses the same condition as the component theme (apiKey and indexName are also required). Before, a missing apiKey displayed an empty DocSearch container instead of falling back to FlexSearch.
  • Header height: defined once in the Tailwind theme (--spacing-header, --spacing-header-offset → h-header, mt-header, scroll-pt-header-offset); tocbot reads its offset from the scroll padding instead of a hardcoded 70.
  • inline_styles option (default: true, unchanged behavior): set it to false to load stylesheets with <link> in production, so they are cached by the browser across pages.
  • styles_extra: no longer overwritten by docs/page.html.twig when a template extends it; documented in the README, with the styles block.
  • theme-color: light and dark meta tags from the pwa.manifest options, unless the PWA component theme is installed (detected by its manifest page, it outputs them).
  • PWA options moved under the pwa key (root manifest and serviceworker are deprecated since the PWA component theme 3.0).
  • Sidebar: the duplicated "Powered by Cecil" mention is removed (still in the page footer).

CI

  • New Check CSS workflow, failing if assets/styles.css is not up to date with its sources.

Breaking changes

  • The global switchLanguage() function is removed (templates overriding the theme and calling it must be updated).
  • The formselect and selector CSS utilities are removed.
  • The PWA component theme 3.x is required (2.x reads the deprecated root options).

Tests

  • Demo built before/after the first part: the HTML only differs where expected; navigation and children lists are identical.
  • tocbot loaded on pages with a ToC (docs/getting-started/, docs/faq/), not on the others (docs/, docs/guides/).
  • Production build: stylesheets inlined by default, loaded with <link> with inline_styles: false.
  • Browser check (Playwright), light and dark themes, desktop and mobile: language dropdown, closing on outside click and Escape (focus restored), aria-pressed updated by the theme toggle.
  • Demo copy with the PWA component theme: theme-color meta tags output once (by the PWA theme), manifest colors from the theme options, no deprecation warning.
  • DocSearch with the statidocs.cecil.app index (Playwright, light/dark, desktop/mobile): light theme and header pixel identical before/after, dark modal fixed.
  • No warning in development and production builds.

🤖 Generated with Claude Code

ArnaudLigny and others added 10 commits October 20, 2026 23:11
Sub-sections and pages are merged and sorted in a single expression (instead
of merging an array at each iteration), and the ancestors ids of the current
page are computed once for the whole sidebar.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`apiKey` and `indexName` are also required: otherwise the header displayed
an empty DocSearch container instead of falling back to FlexSearch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`--spacing-header` and `--spacing-header-offset` (`h-header`, `mt-header`,
`scroll-pt-header-offset` utilities) replace hardcoded values, and tocbot
reads its offset from the scroll padding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- `inline_styles` (default: true) to load stylesheets with `<link>` in production,
  so they can be cached by the browser across pages
- `styles_extra` of a template extending the docs layout is no longer overwritten
- document `styles_extra` and the `styles` block

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Navigating on the change of a `<select>` is not accessible (WCAG 3.2.2): the
selector is now a `<details>` dropdown of links (`hreflang`, `lang`, current
language marked with `aria-current`), closed on outside click or Escape key,
and an inline list in the sidebar. The `language_cookie` option still works.

BREAKING CHANGE: the global `switchLanguage()` function and the `formselect`
and `selector` utilities are removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
"Dark theme" toggle button with `aria-pressed`, instead of a "Change theme color"
button without state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ut waiting for load

The ToC is computed once, outside of any block, and tocbot (stylesheet and
script) is loaded only if it is not empty. Heading anchors are added as soon as
the script runs, instead of waiting for all images to be loaded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Already displayed in the page footer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Light and dark `theme-color` from the `manifest` options, unless the PWA
component theme is installed (it outputs them).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ArnaudLigny ArnaudLigny changed the title Lighter navigation, header height variable, inline_styles option and CSS check Lighter navigation and assets, accessibility, header height variable, inline_styles option and CSS check Oct 20, 2026
ArnaudLigny and others added 3 commits October 20, 2026 23:23
`collapseDepth: 3`: the nested headings are no longer collapsed until their
section is active (default behavior of tocbot, active since its stylesheet is
loaded).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The `manifest` and `serviceworker` options at the root of the configuration
are deprecated since the PWA component theme 3.0. Without it, the `theme-color`
meta tags are output from `pwa.manifest` (detected by its `manifest` page).

BREAKING CHANGE: requires the PWA component theme 3.x (2.x reads the root options).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The modal colors are set with the DocSearch variables (`:root.dark` overrides
its dark variables), instead of overriding its classes. In the dark theme, the
highlight color (hit source, matches, cancel button) is now readable and the
backgrounds follow the theme palette. Only the selected hit background and the
search box text are still set with classes (no dedicated variable).

Tested with the statidocs.cecil.app index: light theme unchanged (pixel identical).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ArnaudLigny
ArnaudLigny added this pull request to stack #6 October 20, 2026 22:11
@ArnaudLigny
ArnaudLigny merged commit 77470c3 into main Oct 20, 2026
3 checks passed
@ArnaudLigny
ArnaudLigny deleted the refactor/review-follow-up branch November 9, 2026 02:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant