Docara Laravel Package

Getting Started

• Update the package (composer update), then rebuild. The first thing to do is diff the build output: 404.html now appears at the deployment base of every non-portal site, and the hero/breakpoint fixes will shift a few pixel values in existing pages.
• Look first at the output root: 404.html, plus _docara/resolved-page-plans.json (the new entry carries "not_found": true). If you have a custom content/<default-locale>/404.md, confirm it was published as 404.html and that the old <locale>/404/ directory is gone.
• Run docara validate page again across the whole site. Page validation previously aborted at the first Composition Recipe page, so pages after it were effectively unchecked; you may now see findings that were always there.
• Run verify-static — it checks the 404 page like any other page, so it belongs in CI alongside the rest.
• First use case: ship the built-in 404 as-is. Add the three lines of host config from the docs hosting page — nginx error_page 404 /404.html;, Apache ErrorDocument 404 /404.html, GitHub Pages automatic — and you are done. Customize copy afterwards.

Implementation Patterns

404 page, three levels of customization. Pick the smallest level that solves the problem:

1. Text only — override error.not_found.* in the default locale's lang.json (error is a new group in the lang.json schema). English and Russian ship built in.
2. Whole page — drop a 404.md at the root of the default locale's content. It replaces the generated content but keeps the site chrome (header, navigation, search, theme).
3. Off — docara.json "not_found": {"enabled": false} restores pre-3.7.0 output.

Keep the search affordance. The default page links home and includes a[data-docara-search-open], which _docara/search.js upgrades to open the search overlay and degrades to a home link without JavaScript. If you write your own 404.md, keep that attribute on your search link — it is the only supported hook.

Author links from the site root. Everything the page links to is addressed from the site root via base_url, because the document is served at whatever missing path the host chose. A relative URL inside your 404.md is resolved from <locale>/404/ (the virtual location it would have had), not from the missing path — so relative asset links behave in a way that is easy to misread. Use root-absolute/base_url paths for anything that must resolve reliably.

Multi-locale sites get exactly one 404, in the default locale, at the root. Do not try to make it locale-aware; the interface strings are overridable only in the default locale's lang.json.

Portal builds are the exception. A portal build has no 404.html because the portal owns it; setting not_found.enabled: true there fails the build with PORTAL_NOT_FOUND_PAGE_FORBIDDEN. If you share one docara.json across a site and a portal, gate the flag per build.

Clean up the renamed view utilities. border-bottom and surface-0 never existed in the bundled SIMAI Framework, so any section or element using them silently rendered nothing. Migrate to border-bottom-1 + border-bottom-solid and bg-surface-0. The old names still render (mapped in place, no duplicates) and each use is recorded in deprecated_utilities under the section provenance or element block data — assert that array is empty in CI rather than waiting for a future removal. Unknown names still hard-fail with DECLARATIVE_VIEW_UTILITY_NOT_ALLOWED.

Split translation reporting. translations status --kind=page|lang now actually filters (it was accepted and ignored). Use it for separate page-content and UI-string dashboards; without --kind you keep the combined report, and accept still defaults to page. An unknown kind fails with TRANSLATION_KIND_INVALID — worth a smoke test if you pass the flag from a script variable.

Held-back pages under translation_tracking.mode: "publish-current" now mark the source text with its own lang/dir on the article and on the outline entries (rail and mobile sheet), while the notice and surrounding UI stay in the page locale. Navigation, breadcrumb and previous/next titles are not marked yet — if you have a screen-reader audit, scope it accordingly.

Gotchas and Tips

• The 404 is deliberately invisible to most of the pipeline. It is noindex, has no hreflang alternates, and is excluded from navigation, backlinks, the search index, sitemap.xml, llms.txt and _docara/page-metadata.json. If you have assertions like "every built HTML file appears in the sitemap" or "page count == sitemap entry count", they will now fail — exclude the not-found page or key off "not_found": true in resolved-page-plans.json.
• Site search will not find the 404 page. Expected, not a bug: it is out of the search index. Do not add it manually.
• A local dev server probably will not show it. The page is served by host error handling, so it only appears when a request for a nonexistent path is routed to /404.html. Test with the real nginx/Apache config or a static host, not with a plain file server.
• Remove your old hero workarounds. The narrow-screen (max-width: 800px) rule that flattened every landing container's vertical padding now skips docara-padding-2xl, so :::hero {padding=2xl} follows its clamp() at all widths. If you had custom CSS or a per-breakpoint override to force tall hero padding on phones, delete it and re-measure at 390 px and 768 px — the same heroes are now 64 px and 108 px taller than in 3.6.x.
• Breakpoints are now in rem, not px. 1152/960 → 72rem/60rem, and 800/700/640/600 → 50rem/43.75rem/40rem/37.5rem. At the 16 px default nothing moves, but at larger browser text sizes the layout now switches earlier — retest at 200% zoom. Any custom CSS or JS that hardcoded the old pixel widths should be converted to the rem values. The shell script now closes the navigation and outline sheets with the exact complement of the stylesheet query, fixing the sub-pixel disagreement at widths like 1152.5 px.
• The hero pause button moved out of the media. It now occupies its own row under the hero content at the inline end, reserving space while it waits for the effect to start and disappearing under reduced motion. Consequence: heroes are ~48 px taller on phones and screenshot baselines will move. If you had CSS compensating for the old absolute placement, drop it.
• Recipe pages no longer spam a false error. The [DOCUMENT_IR_INPUT_INVALID] Cannot compile [...] warning on Composition Recipe pages is gone; validation compiles the same placeholder the build does. Remove any warning filters you added for it — and expect more validation output elsewhere, since validation no longer stops at the first such page.
• Two validation behavior changes to absorb. Links written as inline code (e.g. `![Scheme](/ru/guide/scheme.png)`) are skipped like fenced code, and the advisory PAGE_EDITORIAL_REVIEW_REQUIRED checklist is no longer counted as a build item. The build now reports only things that need fixing; docara validate page is still where the full checklist lives, so move any "TODO because the build printed it" workflow there.
• effects.pause / effects.play can now actually be overridden in content/<locale>/lang.json; the schema and namespace allowlist were missing the effects group, so previously such a file failed validation. If you removed those overrides to make validation pass, put them back. The same class of bug is worth watching for on any newly documented lang.json group.
• Example frames fetch each relative image once. The frame's <base> is now made absolute with the page's origin when the shell moves the document into srcdoc, so Chromium's preload scanner no longer fires a doomed first request. Built pages are unchanged, and file:// previews keep the path-only base — so if you test examples by opening files directly, you still see the old resolution behavior and devtools noise.