{% extends "brickwork/shell/base.html" %} {% load i18n brickwork_components %} {% comment %} Docs shell (ADR-091, icvoss/django-brickwork#439): the documentation surface, a new shell rather than regions bolted onto the marketing shell. It reuses base.html's document skeleton (the {% static %} CSS link, the theme/ density/dir attributes on , the skip link, the no-JS floor, the toast/ modal roots) and adds the [rail | article] two-column layout no other shell carries. A docs page {% extends %} this shell and is itself {% extends %}d by a consuming page (BR-BW-PAGE-001 at docs scope), never {% include %}d. Why a new shell and not marketing regions (ADR-091 decision 1): the deciding fact is source order. A docs page must emit article-then-rail; the marketing shell emits a single content block inside
. A conditional layout inside one template sharing both shapes would be a fork wearing a flag. Named blocks (semver-public, BR-BW-TPL-001), all empty-graceful: content the article body: the one region every page fills. Lands inside the
element, inside
, before the rail in document order (see Source order below). docs_header an optional page header inside the article, above content (e.g. a title, a breadcrumb, a version switcher a consumer composes itself: ADR-091 declines a package-owned version region, since the package cannot know a consumer's version scheme). docs_footer an optional page footer inside the article, below content (e.g. prev/next links, a feedback control a consumer composes itself: ADR-091 declines a package-owned feedback region for the same reason). docs_nav the rail's inner content: a consumer composes {% bw_nav %} here over its own docs_nav_items (brickwork ships no docs nav component: the mechanism is the existing {% bw_nav %}, not a new one). Wrapped in a native
/ disclosure so the rail collapses on narrow viewports with zero JavaScript. docs_site_header SITE-WIDE chrome, OUTSIDE
entirely (see "Site chrome vs page-local blocks" below). Never confuse this with docs_header above. docs_site_footer SITE-WIDE chrome, OUTSIDE
entirely (see "Site chrome vs page-local blocks" below). Never confuse this with docs_footer above. Site chrome vs page-local blocks: READ THIS BEFORE CHOOSING A BLOCK (icvoss/django-brickwork#448 item 1). This shell has two, deliberately distinct, pairs of header/footer seams, and picking the wrong one is the single most likely mistake a consumer makes here: docs_header / docs_footer (and their _region wrappers) are PAGE-LOCAL: scoped inside the
, meant for a version switcher, a feedback control, prev/next links, anything that varies per docs page (ADR-091 decision 2). They sit INSIDE
. docs_site_header / docs_site_footer (and their _region wrappers) are SITE-WIDE: the same header and footer every other page on the site carries (brand mark, primary site nav, legal links). They sit OUTSIDE
entirely, above and below it respectively, exactly where marketing.html's marketing_header/marketing_footer sit relative to ITS
. Filling docs_header when you meant site chrome puts your site nav inside the article, after the skip link's target and ahead of the rail in the accessibility tree, which is not where a repeating site landmark belongs. Before this pair existed, the only override point outside
was {% block shell %} itself, which forced a consumer to reproduce another shell's internal markup (marketing.html's .bw-marketing/.bw-marketing-header/ .bw-marketing-footer classes) just to hang site chrome around a docs page. Overriding {% block shell %} for that purpose is no longer necessary: use docs_site_header_region / docs_site_footer_region instead. Region blocks (ADR-091 decision 2, following #434's shape exactly): a `*_region` block wraps the ELEMENT around an inner content block of the same stem, as a second, outer override seam. Filling only the inner block (docs_nav, docs_header, docs_footer, docs_site_header, docs_site_footer) is unaffected: the wrapper markup is unchanged; overriding the `_region` block instead replaces the wrapper element itself; overriding a `_region` block EMPTY removes the region and its chrome entirely, which the inner-block-only seam can never do. docs_header_region wraps the page header
, inside the article. Carries no landmark. docs_footer_region wraps the whole