Prompt Recipes
Whole pages, described precisely enough that the first build is the one you keep.
Documentation is the only kind of site where the reader arrives with a specific question and leaves the moment they have the answer. That changes the design: navigation has to be persistent, the answer has to be early, and nothing may move under the pointer while someone is copying a command.
Generated documentation sites usually copy the visual language of a blog — a wide content column, a hero, cards — and skip the two things that make docs work: a navigation tree that stays put, and a content column narrow enough to read code against prose.
There is also a specific technical failure worth designing against. A code block with a long line will stretch its container, and because the container is a grid cell, the whole page widens and the layout breaks horizontally. The prompt below fixes the column widths explicitly, so long lines scroll inside the block instead of pushing the page.
The order is the argument. Reordering these is not a layout decision, it is a change to the reasoning.
Product name, version selector, search, and one link back to the marketing site. The version selector belongs here because it changes every other page's content.
Grouped, collapsible, and sticky. Current page marked by weight and a left bar, not just colour. This is the page's map and it must never scroll away.
One h1 per page, answer in the first two sentences, then detail. Reading measure around 72 characters with code blocks allowed slightly wider.
A right-hand table of contents generated from h2 and h3. It is how a returning reader jumps straight to the parameter they forgot.
Horizontal scroll inside the block, never page-level overflow. Copy button, language label, and no line numbers on short snippets.
Two kinds only: a note and a warning. Three or more visual weights and every callout stops being read.
Sequential navigation for guides, none for reference pages. Reference is looked up, guides are read in order — they need different footers.
One question at the end: was this page useful. It is the only cheap signal that a page is failing, and it costs two links.
5 variables. Change one and the text below rewrites itself — nothing else on this page moves.
Parameter tables and copyable examples are the entire page.
The default for anything with more than ten pages.
Build a documentation site for an API reference. Pages are organised by endpoint, each with method and path as the h1, a parameter table, one request example and one response example. Sequential navigation is wrong here; every page stands alone.. AUDIENCE A developer who is mid-task, has the editor open in another window, and will read for about forty seconds before trying something. They arrive from a search result that pointed at one section, not at the page they are now on. STRUCTURE (exactly this layout) 1. Top bar, full width, 56px tall, sticky: product name, version selector, a search field that opens a dialog, and one link back to the main site. No marketing navigation in the docs. 2. Body: a three-column grid — 240px navigation, fluid content capped at 720px, 200px table of contents. Below 1100px the table of contents collapses into a disclosure above the h1. Below 800px the navigation becomes a slide-over triggered by a button in the top bar. 3. Left navigation: Use a grouped tree of five sections maximum, each with a collapsible header and up to eight items. The group containing the current page is open; the others are closed but remember their state per session. Groups are collapsible, the current page is marked with font weight plus a 3px left bar, and the whole column scrolls independently of the content. 4. Content: h1, then a one-sentence statement of what the page covers, then the answer or the first working example within the first two paragraphs. Detail follows. Never open with background. 5. Code: Language tabs above each block, using button elements with aria-selected, and the chosen language persisted for the session. The first tab is the one most readers use, which is usually cURL for APIs and the primary SDK otherwise. Every block has a copy button and a language label. Long lines scroll horizontally inside the block — the page itself must never scroll horizontally. 6. Callouts: exactly two styles, Note and Warning. Inline code is a tinted background with a mono face at 0.9em. 7. Footer of content: prev/next links where the page is part of a sequence, plus a feedback line with two links (Yes / No). STYLE Technical neutral: white content on a #fbfbfc canvas, 240px sidebar at #f7f8fa with a 1px right border, 1px rules under headings, one blue accent for links, mono for all identifiers, no shadows anywhere. MOTION No animation. Documentation is a tool used repeatedly; any movement becomes an obstacle on the second visit. CONTENT RULES - Every procedure is numbered, and every step starts with a verb. - Second person, present tense. You run, not the user should run. - No sentence longer than 25 words in a procedure. - Placeholders in angle brackets and uppercase: <API_KEY>, not your-api-key-here. - Every code sample must be runnable as written, with the placeholder substituted. - No page may end without either a next step or a related link. CONSTRAINTS - Sticky columns must use position: sticky with align-self: start, or the grid stretch defeats them. - The code block container needs min-width: 0 on the grid child, otherwise long lines widen the page. - Body text at least 15px, code at least 13.5px with 1.6 line height. - Heading anchors on every h2 and h3, visible on hover, focusable by keyboard. - Search must be reachable with a keyboard shortcut shown in the field. - Print stylesheet: hide navigation, expand code, keep URLs visible. OUTPUT One documentation page plus the layout shell. Self-contained, no build step.
| Variable | How to edit it |
|---|---|
{{DOC_TYPE}} |
This changes the page template more than any other variable. An API reference page needs a parameter table and two code blocks; a task guide needs numbered steps and a next step. Do not reuse one template for both. |
{{NAV}} |
Grouping is a claim about how the product is understood. Five groups of eight says the product has five conceptual areas; a flat list of twelve says it has none. Pick the one that matches your information architecture, not the one that looks tidier. |
{{CODE}} |
Tabs are only honest if every language is actually supported. A tab labelled Python that shows the same cURL command is worse than no tabs. |
{{STYLE}} |
Dark documentation needs correctly themed syntax highlighting; default token colours on a dark background produce unreadable strings. If you cannot theme the highlighter, use the light style. |
{{MOTION}} |
None is the right default and should be stated explicitly, or a model will add scroll-triggered fades to every section and break the reading flow. |
| Builder | What to do differently |
|---|---|
| v0 | Generate the shell first with dummy content, then a single real page. The three-column grid with two sticky columns is the hard part and it is easier to verify empty. |
| Lovable | It will add a hero and a card grid at the top of the content column. Remove them: a documentation page that opens with a marketing hero pushes the actual answer below the fold. |
| Bolt | Specify the syntax highlighting approach (a named library or pre-highlighted HTML). Left to itself it will inline a large dependency for what is often ten code blocks. |
| Cursor / Claude Code | Generate one page, then extract the shell into a layout so subsequent pages inherit it. Page-by-page generation produces five slightly different sidebars. |
A long line inside a grid column expands the column, and the whole page gains a horizontal scrollbar. The fix is min-width: 0 on the grid child plus overflow-x: auto on the block — without both, the layout breaks at exactly the moment someone is copying a command.
A long page with a static sidebar means the reader at paragraph forty cannot see where they are or jump elsewhere. Sticky positioning with align-self: start is the whole fix, and it is missing from most generated docs.
Pages that open with what the concept is, then why it matters, then how it works, lose the reader who arrived from a search result for one parameter. State the answer first; background goes below, for the people who want it.
Notes, tips, warnings, cautions and dangers in five colours mean none of them registers. Two levels is the maximum a reader can calibrate.