Spaces and shapes

Every space has a shape: a declaration of what it is and what one of its pieces contains. The shape is why a careers space is a careers space and not a documentation space with the word "role" printed on it. Most of the time you never touch it — each type ships with a shape that already fits. But when you need to, you can reshape a space without writing any code.

This guide explains the shape system and how to customize it.

What a shape declares

A space's type declares its shape on three levels:

1. What the space is — what a reader arrives at (a landing page, a list, a board, or a single page), how pieces are ordered (manually, by date, by activity, by votes, or by status), how readers move around (a page tree, categories, tags, sections, or nothing), who may add pieces (your team, members, or anyone), and what a row in the listing shows.

2. What one piece contains — the named sections (slots) a new piece opens with. A blog article has a standfirst and a body; a careers role has a summary, responsibilities, requirements, and more; a documentation page is a blank canvas with no sections at all.

3. Facts a piece carries — the short, fixed fields beside the writing: a location, a date, a salary band, a link, a version. These appear beside the editor and in the page's own structured markup.

Nothing in a shape is a cage. Every section and field is optional — an author can leave any of it empty or delete it, and a piece still saves. The shape is a scaffold and a starting point, not a set of required boxes.

Where to customize a shape

Open the space in the studio, open the Settings fold in the panel, and the first group is Shape. Everything below happens there.

A key idea: what gets stored is only the difference between the shape you edit and the shape the space would have had anyway. Opening the shape panel and closing it writes nothing. This "patch, not copy" approach means an improvement to a type's default still reaches your space, except for the specific things you changed.

What this space is

The first card lets you change what readers arrive at, how pieces are ordered, how readers move around, and who may add pieces — each a single dropdown. Below that, A row in the list shows lets you toggle which facts appear on each item in the listing. Title always shows; a fact this kind of piece does not carry is simply skipped rather than faked.

Changing any of this does not move anything you have already written.

What one piece contains

The second card is the list of sections (slots) a new piece opens with. For each slot you can:

• Rename it — type a new label directly.

• Reorder it — use the up and down arrows.

• Remove it — use the × button.

• Edit its details — press Edit to expand it. There you set what usually goes in it (prose, a list, steps, or a table), how it is published (labelled, as a lede, or as plain prose), whether it is asked for, a hint (the sentence under the input), and an example — real placeholder text that an author sees and that an AI agent connecting to your space uses as a model of what to write.

Add a new slot with the Add a slot field at the bottom. As you build the outline, a live preview — A new piece opens as — shows exactly the blank page an author will get.

Whatever you build here is also the outline handed to an AI agent that connects to your space, so the same declaration serves your authors and your automation.

Kinds of piece

Below the slots you can offer more than one kind of piece. Set what a new piece starts as, apply one of the type's built-in kinds as the default, or — the part that makes this real customization rather than a menu — save the slots you have built as your own named kind. For example, a support forum where every topic should be a bug report can save a "Bug report" kind, and authors pick it when they start a topic. Your own kinds are marked "yours" and can be removed.

Facts a piece carries

The third card is the list of fields — short fixed values like a location, a date, or a link. Rename a field, change its value type (text, choice, date, link, number, and so on), reorder it, or remove it. If you set a field to choice, a box appears to enter the comma-separated options — without which the choice would be a dead end.

Add a new field with the Add a fact box at the bottom.

Saving, and going back

• Save shape writes your changes. New pieces here will open as your outline.

• If you have customized the shape, Back to the default puts the space back to how that kind of space normally works.

Because only your differences are stored, resetting is a clean return to the type's shipped shape.

What's next

• Editing in the studio — writing and arranging content once the shape is set.

• Your first space — the eleven types and what each is for.