{% extends "brickwork/shell/docs.html" %} {% comment %} A documentation home: the page a reader lands on at /docs/, whose job is orientation, not exposition. It answers "what is here and where do I start", never "here is a topic". COPY THIS FILE into your project and edit it. It is not on the template loader path, so you cannot extend it (ADR-056). What your view must supply: nav_items / nav_active the rail's NavItem tree, as bw_nav expects it docs_search_action the URL bw_search submits to (GET) has_published_docs False shows the empty state instead of the start-here cards; True (the normal case) shows them. See the EMPTY STATE paragraph below. The headings and copy below are typed into the template, which is where you change them. A docs home is read by two different people, and a signpost page has to serve both in one screen. A first-time reader has no idea what exists and needs a small, confident set of doors in: three, not thirty, each naming a concrete next step rather than a topic label. A returning reader already knows roughly what they want and is scanning for the fastest way back to it, which is why search leads the page rather than sitting in a corner, and why a short, named list of frequently-opened pages follows it. Everything past that (the version callout) is context a reader consults, not a door a reader walks through, so it sits after the bands that actually move a reader somewhere. This is why the page is NOT a directory listing of every doc in the tree. A flat list of forty links is a sitemap wearing a homepage's URL; it makes the reader do the ranking the page should have done for them. The three start-here cards ARE the ranking: each is a deliberate editorial choice about which door most first-time readers should walk through, typed by a human, not generated from the nav tree. Search leads rather than trails for the same reason product documentation sites converge on this layout: a returning reader with a specific question already knows the words for it, and asking them to find the right card before they can even search is the slower path. The nav rail (bw_nav, in docs_nav) is the THIRD way in, for a reader who wants to browse the whole tree rather than jump to one page; it is not repeated in the body, since the rail is already always on screen at the layout breakpoint and the body would just be duplicating it. The start-here cards are HAND-WRITTEN bw-card markup, not {% templatetag openblock %} include "brickwork/components/_card.html" {% templatetag closeblock %}: {% templatetag openblock %} include {% templatetag closeblock %} is a void tag, it cannot wrap a body of markup, and _card.html's body region is a block, unreachable from an include for exactly that reason (only title reaches it as a context variable, ADR-090 decision 3). A card whose body is a paragraph, which every start-here card here needs, is authored as plain bw-card markup instead, matching the class list _card.html's own href branch renders (bw-card bw-card--interactive, plus bw-card--bordered when bordered). No breadcrumbs: this page IS the root of the section a breadcrumb trail would describe, so a trail here would read "Documentation" with nowhere to go, which is not a trail, it is a single inert word. The docs shell has no breadcrumbs block of its own for exactly this reason (see the shell's own Accessibility note); a page one level down the tree is a better place to introduce them. EMPTY STATE, decided rather than skipped: a documentation site that has shipped its shell before its content is a real state, most likely the very first time this page is ever deployed. has_published_docs=False swaps the start-here band for _empty_state.html rather than three cards linking nowhere real. Search and the popular-pages band still render even then: search legitimately returns nothing yet, which is that endpoint's own state to handle, not this page's, and an empty rail is the rail's own concern too. No separate "search returned nothing" state is built here: this page never renders search RESULTS, only the box that submits to them, so a no-results state belongs to the results page this one links to. LOADING: not applicable. This page has no client-side data fetch of its own; every band renders from context supplied at request time, so there is nothing here to be in flight. A future version with a live "recently updated" band pulled in by htmx would need one; this one does not. ERROR: not applicable to the page itself, for the same reason: nothing here calls out to a service that can fail independently of the page render itself. bw_search's own action is a plain GET a browser follows like any link, so an unreachable search endpoint is that endpoint's error page to render, not a state this page has to anticipate. States: has_published_docs is the one real branch on this page (see EMPTY STATE above): True renders the start-here cards, False renders _empty_state.html in the same band position. bw_search carries its own scoped/unscoped state, unused here (no scope= passed, since a docs home searches the whole site, not a pre-scoped subset). Every other band is static: no loading state and no per-band error state (see LOADING/ERROR above for why neither applies to this page). Accessibility: inherits the docs shell's skip link and lang/dir/theme attributes from base.html (see shell/docs.html's own header). Each band is a labelled
pointing at its own visible

, so a screen reader user gets the same section structure a sighted reader sees from the headings, never a hidden heading standing in for a visible one (this page has no band whose title is already carried by a composed component, unlike analysis-dashboard.html's chart band, so every heading here stays visible). bw_search renders a role="search" landmark with a visually hidden input label, not a placeholder alone (see _search.html's own header). Each start-here card is a real element, native focusable and activatable, not a div with a click handler standing in for one; its whole surface, heading and paragraph included, is the one link, so a reader can activate it from anywhere in the card, not only a small "read more" fragment. No reading on this page rides on colour: the callout's kind is carried by its title text, not its accent tint alone (WCAG 1.4.1, see components.css's own callout header). Responsive: no breakpoint switch of its own; inherits shell/docs.html's single-column-to-two-column layout switch at --bw-breakpoint-lg (see the shell's own Responsive note) and its rail-to-disclosure collapse below it. bw-band-grid--3 (the start-here cards) is content-driven rather than breakpoint-driven: it reflows from three columns to one once a card no longer fits an 18rem track, which on a typical device happens well below the shell's own lg breakpoint, so the two layout systems compose rather than fight. bw_search has no width-dependent CSS of its own; its input takes min-inline-size: 0 so it contracts inside a narrow rail-collapsed layout rather than forcing the page wide (see _search.html's own Responsive note). {% endcomment %} {% load brickwork_components brickwork_interactions brickwork_nav %} {% block page_title %}Documentation - Northwind{% endblock %} {% block docs_header %} {% include "brickwork/components/_page_header.html" with title="Northwind documentation" description="Everything you need to integrate Northwind: guides for getting connected, the full API reference, and answers for when something goes wrong." %} {% endblock %} {% block docs_nav %} {% bw_nav nav_items nav_active %} {% endblock %} {% block content %}
{% comment %} BAND 1, the returning reader's door. Search leads the page rather than sitting in a header corner, because a reader who already knows what they are looking for should never have to scan the start-here cards first to confirm none of them is it. docs_search_action is the consumer's own search view; brickwork renders the form and the query field only (see _search.html's own header), so what "search" means here is entirely this project's to define. {% endcomment %}

Search the docs

{% bw_search docs_search_action placeholder="Search guides, API reference, changelog..." %}
{% if has_published_docs %} {% comment %} BAND 2, the first-time reader's door, and the band this page exists to get right. Three cards, not a list of every section, because the ranking IS the content: each card is a deliberate editorial choice about which door most first-time readers should walk through, in the order they should walk through them. Hand-written bw-card markup, not an include (see the leading comment above for why); the class list matches _card.html's own href branch exactly: bw-card bw-card--interactive bw-card--bordered. bw-band-grid--3 is the app-family arrangement primitive (ADR-090 decision 1): never bw-feature-grid--3, which is marketing-family and fails tests/test_family_boundary.py on this shell. {% endcomment %}

Start here

Getting started

Connect a sandbox account, send your first request, and see a real response in under ten minutes. Start here if this is your first time with Northwind.

Guides

Task-by-task walkthroughs for the things most integrations need: authentication, webhooks, pagination, and handling rate limits.

API reference

Every endpoint, field and status code, generated from the same schema Northwind runs in production, so it never drifts from what the API actually does.
{% else %} {% comment %} EMPTY STATE: no published section yet, the day-one state of a docs site whose shell has shipped ahead of its content. size="sm" is deliberately NOT used here: this band still fills the page's primary orientation slot (the reader's actual next step, not a nested aside), so it earns the full-scale heading and primary-button treatment size="sm" exists to demote away from. {% endcomment %}

Start here

{% include "brickwork/components/_empty_state.html" with heading="Nothing published yet" body="The first guides are being written. Check back soon, or contact support if you were sent here looking for something specific." icon="document" action_href="/support/" action_label="Contact support" %}
{% endif %} {% comment %} BAND 3, the returning reader's shortcut. A short, named list rather than "recently updated" or any other mechanism this page cannot generate on its own: authored inside .bw-prose, flat, since a lede paragraph plus a plain link list is genuinely prose-shaped content, and .bw-prose's own direct- child rhythm rule (.bw-prose > * + *) requires flat authoring, never an extra wrapping
, or the spacing between the paragraph and the list collapses. {% endcomment %}

Pages other readers open most often this month, if you are not sure which of the above to pick.

{% comment %} BAND 4, context rather than a door: what version this documents and how to get help, which a reader consults rather than walks through, which is why it sits last. Hand-authored bw-callout markup (no _callout.html ships; the classes are the whole contract, per components.css's own header) since the content is two short lines, not a structural region with named slots. {% endcomment %}

You are reading the docs for API v3

Still on v2? See the v2 documentation and the migration guide. Can't find what you need? Contact support, we usually reply within a working day.

{% endblock %}