flows.md · documentation

Layouts#

On a site, almost every page has the same things around it: the menu on top, the footer below, sometimes a side column. Copying that onto each page works until the day the menu changes — and then there are ten pages to fix.

A layout is an ordinary page that has a :::slot. What is around the slot is what the pages have in common. The other pages wear the layout: a reader gets the page inside it.

Writing a layout#

:::nav
**[Studio](./)**
---
- [Work](./work)
- [About](./about)
:::

:::slot
:::

:::footer
Made here.
:::

A layout's links are relative to the page that declared it — the site's root. ./about is that site's "about" on every page that wears the layout, and the same layout serves two sites, each with its own links. The link to the page being read is marked.

Where layouts live#

In the space's layouts page: the layout named site is the page /@you/layouts/site. It is a page like any other — it has the editor, languages and history — which is why this page, /@docs/layouts, also holds @docs' own layouts. The layouts of your spaces show together at /~layouts, beside your views.

Wearing it#

One fence with the layout's name, once, on the site's root page:

```layout
site
```

A name, not an address: no path, no tilde.

It applies to the page and to every page below it. The order is the themes': the page's own fence, then the nearest page above, then nothing.

In the fence	What it does
`site`	wears this space's layout `site` (`docs/guide` works too: a page inside another)
`cascade: false`	only this page wears it, the ones below do not
`none`	this page (and the ones below) wear nothing

A page that has a slot never wears a layout by inheritance — only when it names another itself.

Replacing a part on one page#

A layout may have named places, each with what shows when nobody says otherwise:

:::slot name:cta
## Let's talk
[Write to us](./contact)
:::

A page replaces that part with :::fill:

:::fill name:cta
## We are hiring
[See the roles](./jobs)
:::

The names are main (the page's content), hero, aside, top, bottom and cta. A :::fill for a place the layout does not have stays where it was written — nothing you wrote disappears.

A layout that wears another#

The docs layout can wear the site's: the site's gives the menu and the footer, the docs' adds the side column around the slot.

```layout
site
```

:::section width:wide
:::split rail:16 sticky:first
**Guide**

[Getting started](./start)
---
:::slot
:::
:::
:::

A site without the app around it#

A reader gets a page inside flows.md: the header with the trail of pages around it. A site with its own menu asks to be seen on its own, and says so with a view block:

```view
standalone: true
```

Then a reader gets the page alone, with a small mark in the corner (the visibility tag and sign-in, which never disappear), with no anchors beside the headings and no outline unless the theme asks for them. Whoever may edit still gets the app around the editor. Like the layout, it applies to the page and to the pages below it: put it once on the site's root; standalone: false turns it off for a page and the pages below it. It is a way of seeing, not a look, so it is not in the theme (the theme's old chrome: site still works).

Seeing it#

The editor shows the page inside the layout it wears, and you write where the content goes; the layout's links work and open the other pages, in the editor too. To see exactly what a reader gets, open Page in the editor's menu and choose See it as a reader — or add ?as=reader to the address; its links stay in reader mode.

An example you can open#

The Orbit showcase has three pages and one menu: it is in layouts / orbit, with an English version, and all three wear it by saying just orbit.