Block article template

The Buttons block article is the canonical reference for every block reference page in this docs site. When documenting a new block, open src/content/docs/blocks/questions/buttons.mdx and clone its structure section by section, replacing block-specific content as you go.

This page lists the structure, conventions, and components used by the canonical article so you can scan them at a glance.

Why a single canonical example

A real, complete article shows tone, depth, and component composition better than a synthetic template ever could. Maintain shape consistency by mirroring Buttons rather than ad-libbing. If a block genuinely needs a section Buttons does not have, add it — but keep the existing sections in the same order so readers can navigate any block article the same way.

Required sections, in order

Every block article must include the following sections in this order. Section headings are fixed wording — match them exactly, substituting the block name where shown in brackets.

1. Frontmatter — title (the block name), description (one sentence covering what the block does and the primary outcome).
2. MDX imports — Starlight components (Aside, Badge, Card, CardGrid, Steps, Tabs, TabItem) plus all screenshot imports.
3. One-paragraph opener — what the block does and the situation that calls for it. No heading.
4. “Applies to” badges — <Badge> row covering Builder, Widget, Results, and Contact fields where applicable.
5. Three-card overview — CardGrid with three cards: Best for, Stores, Routes (or block-equivalent terms).
6. Sibling-block aside — <Aside type="note"> pointing readers to the closest alternative block when their use case fits it better.
7. ## At a glance — capability table with Capability and Supported columns.
8. ## Example — concrete scenario, then a builder editor screenshot (<figure> with caption), then a widget preview screenshot (<figure> with caption).
9. ## When to use [Block] — bulleted “good use cases” list, then a Use a different block when list with explicit redirects to other blocks.
10. ## Add a [Block] block — <Steps> walkthrough from opening the builder to connecting the next path.
11. ## Configure the question — guidance on the question text with Good and Avoid quoted examples.
12. ## Configure options (or the block’s setup section) — what is configurable, what is not. Use ### subsections for nuanced fields that deserve their own explanation (see the Buttons article’s Stored value (optional) subsection).
13. ## Save the answer — workflow answers behavior, contact field binding, and a suggested-field table when applicable.
14. ## Selection mode or other behavior section — use <Tabs> for mutually exclusive modes the block exposes.
15. ## Layout or visual options — table of options with Use when guidance.
16. ## Common patterns — CardGrid with four real-world use-case cards.
17. ## Answer output — JSON shape in a fenced block, then a field-meaning table. Use distinct example values across ids, labels, and values so readers see the difference.
18. ## Routing behavior — table of mode → routing rule, plus any pre-publish requirements.
19. ## Validation and limits — explicit list of failure conditions the validator enforces. Do not list missing or unimplemented features here; this section is customer-facing.
20. ## Troubleshooting — table of Problem → What to check.
21. ## Related articles — bullet list of internal links to sibling and supporting articles.

Conventions

• Voice: second person, present tense, plain language. No jargon a non-developer would not know without explanation.
• Quoted examples: use blockquotes for sample question text, both good and bad.
• Asides: type="note" for pointing to alternatives, type="tip" for advice that prevents future pain. Always set a title.
• Tables: preferred over prose for capability lists, routing rules, contact-field suggestions, and troubleshooting.
• Tabs: use only for mutually exclusive modes (single vs multiple, etc.), not for “alternative” content.
• Steps: use for ordered procedures with concrete UI verbs (“Open”, “Add”, “Choose”, “Connect”). Keep each step to one sentence.
• Figures: every screenshot wrapped in <figure> with descriptive alt text and a <figcaption> explaining what the reader is looking at.
• Internal links: absolute paths starting with /, ending in /. Example: /blocks/logic/condition/.
• File extension: use .mdx (not .md) for any block article that imports Starlight components or screenshots.

Verifying accuracy before publishing

Before merging a new block article, confirm every claim against the implementation in app/, widget/, and api/ (or laravel/ once ported). The article must not describe configuration fields, validation rules, or output shapes that do not exist in the code. If the builder UI exposes a field, document it. If the validator rejects something, list it. If the runtime executor produces a structured output, mirror its real shape.

Source

The canonical article lives at src/content/docs/blocks/questions/buttons.mdx. Open it locally and clone it as the starting point for any new block reference page.