---
title: "The shape of a page"
description: "What a page consists of, and where its columns stand."
canonical: page-shape.html
navigation-title: "Page shape"
---
# The shape of a page
- [layout](#layout)
- [hero](#hero)
- [hero-figure](#hero-figure)
- [band](#band)
- [split](#split)
- [half](#half)
- [grid](#grid)
What a page consists of, and where its columns stand.
## layout
Not a directive. A field at the top of a document, beside the navigation
title, and it decides which shape the page takes.
```text
:navigation-title: Overview
:layout: marketing
================
What this is for
================
```
**`layout`**
- Type: string
- Default: "default"
`marketing` renders the page as a run of full-bleed bands with no rail.
Anything else, and a page with no such field, is the manual shape. The
toctree in a rail on the left, the trail above the title, the text held
to sixty-six characters.
Both shapes carry the same bar and the same footer, because a reader must
never have to work out which site they are on. The body changes.
> [!NOTE]
> A field is invisible only because something claimed it. One nobody
> claims renders as a definition list in the body, which is what a
> misspelt field looks like. `:laoyut: marketing` prints the word and the
> value above the title of a page that is still a manual.
## hero
The opening claim of a marketing page, beside one decorative image. It goes
right after the document title, so the title stays the page's real heading,
browser title and source for navigation.
The opening summary belongs inside the directive.
Copy the example project and replace its content.
[Publish a first site](../quickstart.md)
[Read the example](../example.md)
The document title stands above it in the source and is not part of it. On the
page the hero takes the title into its first column, beside the picture. That
holds in every layout, and for any heading the hero follows directly.
The argument is the image source. The theme writes `sds-hero`. At a narrow
viewport the two halves become a column by the rule of every split in the
system. Content after the hero and
before the next band stays part of the opening section.
**`alt`**
- Type: string
- Default: ""
What the image shows, when it adds a meaning the copy lacks. Leave it out
for a decorative illustration whose subject already has its name beside
it.
**`plain`**
- Type: flag
Takes the frame off the picture, for an illustration with no edge of its
own. A screenshot or a drawing keeps its frame.
**`eyebrow`**
- Type: string
The line over the title: what kind of page this is.
**`action`**
- Type: string
The press, in words, with a verb first. With no `href` no button draws.
**`href`**
- Type: string
Where the press goes.
**`icon`**
- Type: string
The name of a glyph in front of the press.
**`second`**
- Type: string
The way for a reader who is not ready, quieter than the press. It draws
only beside a press.
**`second-href`**
- Type: string
Where the second way goes.
**`align`**
- Type: start | center | end
- Default: center
Where the copy and the picture stand against each other: at the top, level,
or at the foot.
**`leads`**
- Type: start | end
- Default: start
Which half comes first once the two have stacked. `end` puts the picture
above the copy on a phone.
## hero-figure
The other half of a hero, written rather than named as a file. It stands in the
body of a `hero`. What it holds is the half beside the copy: a diagram, code, a
card or a picture. An element there reads the page's tokens and follows
the colour mode a reader chooses. A picture file cannot do that. The image
argument of the hero can then stay away, and a `hero-figure` wins over it.
Copy the example project and replace its content.
```bash
composer require typo3/soul-guides-theme
```
The theme writes it as the child of `sds-hero` with `slot="figure"`. It takes
no options. The hero's `:align:` and `:leads:` place it.
## band
A full-bleed section of a landing page. The ground runs edge to edge, and
the content inside keeps the page measure.
## This heading is a band, on a manual page
And the paragraph after it, beside the section
rather than inside it. What follows a band
belongs to it on a page built out of bands.
This page is not one.
On a page whose layout is not `marketing`, that is the whole of it: a
section inside the column, not a ground edge to edge. The page decides the
shape a band takes, not the band.
**A band does not wrap a page in itself. It opens one.** What follows belongs
to it until the next band starts. What stands before the first one is a
band as well: a page opens on the canvas. That is the whole syntax, and it
has a reason beyond a tidy source.
A band is full-bleed and takes the page inset itself. So a band inside another indents its text by a gutter nobody
asked for, and stops at the width of its parent.
```text
.. band:: What it costs
:quiet:
:id: pricing
Everything from here, up to the next band.
.. band::
And this is back on the canvas.
```
That one is a print, not a render, and it is the only source on this page
that is. What a band does with the content after it happens where the page
is bands. Here it renders as two sections with the text loose between them,
which is what the example above shows.
A page with no band at all is the single band it looks like.
**`quiet`**
- Type: flag
The second ground. Quiet and plain in turn make a run of bands read as a
sequence, not as a wall. Two bands in a row share one hairline.
**`id`**
- Type: string
An anchor, so a link elsewhere on the site can land on this section.
**`the heading`**
- Type: string
The band's argument. It is an option and not a section heading, because
a section heading inside a directive is not one. reStructuredText parses
sections at document level. A line with `====` under it, written in
here, ships both the line and the equals signs as text.
The landing page of [the example project](../example.md) is the same
directive at home, with the run of them at work.
## split
Two of anything, side by side until there is no room for two.
A paragraph and a picture are two blocks,
so they stand as two columns and nothing
here says which is which.
**Every block in it is a column.** That is the whole rule, and why the
example above needs nothing to mark its halves. A paragraph is one block,
and a figure is another. The moment a side is a heading, its paragraph and
a press, those are three columns, unless something says where the side
ends. `half` is that something.
No width and no count anywhere. The halves fold under each other by their
own minimum, the way every set in this system reflows. The class is
`.sds-split` in [Page layout](../../frontend/layout.md).
**`align`**
- Type: start | center | end
Where the shorter half stands against the taller one: at the top, level
with it, or at the foot. `start` is the default, and `center` is what
a line beside a picture usually wants.
**`leads`**
- Type: start | end
Which half comes first once the two have stacked. `start` is the
written order. `end` puts the second half above the first. A picture at
the end of the line on a page, and above the sentence it illustrates on a
phone. It changes nothing while the two fit side by side. The order a
reader reads is not the source order at every width, and the layout
cannot work that one out itself.
## half
One side of a split: the blocks that stand together as one column.
## Two paragraphs, one side
This is the first of them, and it is not a
column.
This is the second. Without the `half`
around both, it is one.
It takes no position of its own. The split decides where a half stands,
because the other half is what it stands against. Anywhere else it is the
blocks it holds, in the rhythm a page keeps between them. Its optional
argument becomes an `h2` inside the column. Use it when the heading names
that side, not both sides of the split. A reStructuredText section heading
has no place inside a directive.
**`align`**
- Type: start | center | end
Where this half stands, top to foot, when it differs from the split's
`align`. It is the same three positions, for one half.
## grid
A set read side by side, reflowed by its own minimum width.
**[What it is](../index.md)**
A badge above the title, and the whole
card lit at the top of its frame under
the pointer. A paragraph long enough to
decide how tall this row is. That is the
only thing the card beside it has to
agree with.
**[What it costs](../installation.md)**
One Composer package.
No column count, and that is the design. Three across on a desk, two on a
tablet, one on a phone, from how narrow an item can get, not from a
breakpoint. It holds cards, figures, or anything else read as a set. Each
item draws itself, and the grid decides how many stand in a row.
The two above differ in length on purpose. A set whose items say the same
amount cannot show what the wall does. The short one draws to the row, not
to its own sentence. The element is `sds-grid` in
[Content](../../frontend/components/content.md).
**`the argument`**
- Type: default | wide | dense | flush
How much room one item needs, said as what the items hold, not as a
number. `wide` for a card with a picture and a paragraph, `dense` for
a figure or a name and a glyph. `flush` takes the gutter out, so the
set shares a hairline and reads as one wall. Without it the set gets the
width every set gets. A name the element does not define falls back, and
does not pass through. `:variant:` says the same thing as an option.
**`columns`**
- Type: number
This many across, while each item keeps its minimum. A narrower room
takes fewer. For a set whose rows are the point: two by two, or three
and two.
**`align`**
- Type: start | center | end
Where a shorter item stands in its row: at the top, level, or at the foot.
With nothing said, it fills the row, so feet line up. `flush` ignores it,
because a tile that stops short leaves a hole in the wall.