/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog

Hero

Landing-page hero — a full-width banner, an inset card, or your preset's home hero.

4 min read

A landing-page header. Without title it has two variants: the default full-width banner, and a card that sits inset in the content with room for a code sample. With title it's your preset's home hero — the top of a docs home.

Default

mdx
<Hero>
# Build with the Acme API
Everything you need to move money programmatically.
[Get started](/quickstart)
</Hero>

A centred banner with a soft gradient. Set background="none" to drop the gradient, which is useful when the page already has a custom background.

Card variant

mdx
<Hero variant="card" eyebrow="Acme API">
# Move money anywhere in the world.
One API for cross-border payouts and instant settlement.
[Get your API keys](/authentication) [Read the quickstart](/quickstart)
```bash
curl https://api.acme.com/v1/transfers \
-H "Api-Key: $ACME_API_KEY"
text
An inset panel. On doc engine v1 it is an inverted surface that stays dark on a
light page; on doc engine v2 it follows your preset's card surface. Content
sits on the left; a code fence inside the hero becomes a second column beside it,
collapsing underneath below 900px.
| Attribute | Description |
|-----------|-------------|
| `variant` | `card` for the inset panel. Omit for the default banner |
| `eyebrow` | Small uppercase label above the headline. Also the kicker of a [home hero](#home-hero) |
| `background` | `none` to drop the default banner's gradient |
The first link is the primary action; any further links render outlined. Write
them on one line — they are grouped into an action row automatically.
## Home hero
On a [doc engine v2](/platform/presets) site, give `<Hero>` a `title` and it
draws your preset's home hero: the headline, a lede, buttons and the home
search box, styled like the rest of the preset's home.
```mdx
<Hero title="Build with Acme" description="Payments, payouts and webhooks in one API." install="npm install @acme/sdk" eyebrow="Acme docs">
<SearchBar mode="both" suggestions="popular" />
[Quickstart](/quickstart) [API reference](/api-reference)
</Hero>
AttributeDescription
titleThe headline. Selects the home hero
descriptionThe lede under the headline
installA shell command with a copy button. Console, Plain, Orbit and Grid show it in their own install block. Workbench, Paper, Atlas and Margin have none, so it's a compact line inside the hero, above the search box
eyebrowThe small label above the headline, in presets that draw one
aligncenter (default) or left. See Starting the hero on the left

Inside it:

•
a <SearchBar> goes in the hero's search slot, always as the home search box — an input readers type into, with results as they type or a question for the assistant (see Typing in the home search box);
•
a line of links becomes the buttons — the first is the primary one;
•
anything else renders below the hero.

On Paper and Atlas, the hero's search box shows the <SearchBar>'s own placeholder and suggestions. On Plain, a hero with both install and a <SearchBar> draws the title and lede, then the Install code block, then a Get help search box with the <SearchBar>'s placeholder and the ⌘K hint:

mdx
<Hero title="Acme documentation" description="Payments, payouts and webhooks in one API." install="npm install @acme/sdk">
<SearchBar placeholder="How do I connect a custom domain?" />
</Hero>

A page whose body opens with <Hero title> has no page head — no breadcrumbs, <h1>, description or reading time — because the hero is the head. That holds on any page, so the frontmatter title and description stay for the browser tab, search and link previews and are not shown twice.

An index page that uses <Hero title> is the docs home as you wrote it — see Home page. Pair it with layout: wide for a home with no sidebar.

Starting the hero on the left

By default the home hero keeps your preset's own alignment: Workbench, Console, Atlas, Plain and Margin draw it in a column centred on the page, and Orbit centres its text. With align="left" the eyebrow, headline, lede, buttons, install line and search box start on the left instead:

mdx
<Hero title="Ashmont Publishing" description="How we work, what we value and where to find things." align="left">
[New here? Start with onboarding](/people/onboarding) [How we work](/company/how-we-work)
</Hero>
<SectionCards />
•
On a full-width home (layout: wide), the hero lines up with the header's left edge, and the home components after it (<SectionCards>, <LatestUpdates> and the others) line up with the hero, so the page shares one left edge.
•
In a page's content column, the hero already fills the column, so only Orbit changes: its text starts on the left.
•
Paper and Grid already start their hero on the left, so align changes nothing there.
•
On phones and tablets the hero keeps the same left edge as the page's text.

Any other value is ignored: the build warns and keeps the preset's own alignment, and the editor flags it with center and left as the choices.

Note

title, description, install and align are doc engine v2 only. A v1 site ignores them and draws the banner.

Theming

On doc engine v1 the card draws from hero-card-bg and hero-card-fg, which are separate tokens because the panel is an inverted surface and cannot be derived from the page background. Doc engine v2 ignores those tokens and uses the preset's card surface. Buttons use the accent tokens.

Was this page helpful? Yes No
Previous
Next
Product
Resources
Company
© 2026 SyntextBuilt with Syntext