# Model your content

> When to use a content type, a component, a slot, a reference, a shared section, a global entry or a taxonomy, with a worked model for the Northwilds website.

Source: https://docs.bifrostorbit.com/cms/developers/model-your-content/

A content model is the set of content types, components and fields your editors fill in. A good one lets editors build pages without asking you, and lets your website render them without special cases. This page explains each building block, when to reach for it, and shows the model behind a Northwilds journal.

## The building blocks

| Building block | What it is | Use it for |
| --- | --- | --- |
| **Content type** | A kind of entry, with its own fields | Things with their own address or identity: a page, a journal post, a trip report, an author |
| **Component** | A block editors place on a page, with fields | The parts a page is built from: a hero, a text section, a gear list |
| **Slot** | A Component or Components field on a component | Blocks inside a block: the items in a gear list, a button in a hero |
| **Reference** | A Reference or References field | Pointing at another entry that has a life of its own: a post's author, related posts |
| **Link** | A Link field | Sending a visitor somewhere: another page, which then follows it when it moves, or any address |
| **Shared section** | Blocks kept in one place and shown on many pages | A newsletter sign-up or an opening hours band that must read the same everywhere |
| **Global entry** | An entry of a content type marked as global, read by key | Content that appears once per website: the header, the footer, the cookie notice |
| **Taxonomy** | A list of terms, kept under **Taxonomies** | Topics, activities or seasons that entries are tagged with and visitors filter by |

## Content type or component

Ask whether the thing has an address or is listed on its own.

- **A content type** if it does. A journal post has an address, appears in lists and sitemaps, has SEO settings and is published on its own. Its own fields hold what every entry of the type has, such as an excerpt, a publishing date and a cover image.
- **A component** if it only exists as part of a page. A text section or a gear list has no address and is never published on its own.

Keep the entry's own fields to what your website needs outside the page body: what lists, cards, feeds and search show. Everything that makes up the page body belongs in components, so editors can reorder it, and a new kind of section is a new component rather than a new field on every type.

Every entry of your own content types gets an address, from its folder and slug, or from the type's **Address** setting, such as `/journal`. Entries that are not really pages, such as authors, still have one. Give them a folder such as `/authors` and an author page your website renders, which is usually worth having anyway.

## Slot or reference

Both put one thing inside another. The difference is who owns it.

- **A slot** holds blocks that belong to the parent and to this page only. The items in a gear list are part of that list. Deleting the list deletes them. Editors fill them in place.
- **A reference** points at an entry that exists on its own and may be used in many places. An author writes many posts. Changing the author's biography changes it on all of them, and the author can be published, translated and listed separately.

If editors would want to reuse it on another page, or it should appear in a list of its own, make it an entry and reference it. Otherwise use a slot.

Slots arrive in the block's `children` and on the field itself, so your component can read `block.items`. References arrive as ids, or as entries when you read with `include=references`. See [Field types](https://docs.bifrostorbit.com/cms/developers/field-types/).

## Reference or link

Use a **Link** field when the point is to send the visitor to a page: a button, a card, a "read more". It arrives with the page's current `href`, so a moved page never breaks it. Use a **Reference** when your website needs the other entry's fields, such as the author's name and photo next to a post.

## Shared section or reference

A shared section is a group of blocks editors reuse on many pages, edited once. Pages show its blocks as if they were their own, so your website draws them with the components it already has, and needs no code for the section itself.

Use a shared section when the same blocks should appear on several pages and editors decide where. Use a reference when the reused thing is structured data your component renders, such as an FAQ entry or a testimonial. Use a global entry when it appears once on every page, such as the footer.

## Taxonomy or select field

A **Select** field's choices live in the schema, so only someone who can change the schema can add one. A **taxonomy** is edited by editors under **Taxonomies**, has labels in each language, and can be read by your website with `GET /taxonomies/{key}` to build filters. Use a select for choices your code depends on, such as a heading level or a layout. Use a taxonomy for anything editors may want to extend, such as topics or activities.

## Regions and languages

Regions and languages are not part of the model. Every content type and component works in every region and language. Each language holds its own copy of an entry, linked to the others as translations of the same thing. Turn on **Differs by region** on fields that should keep their own value when a region's copy is updated from its source, such as a price or a shop's phone number. See [Regions and languages](https://docs.bifrostorbit.com/cms/developers/regions-and-languages/).

## A worked model: the Northwilds journal

The Northwilds journal has posts about trips and gear, written by the people who lead the trips.

**Content types:**

| Key | Fields | Why |
| --- | --- | --- |
| `journalPost` | `excerpt` (Long text), `publishedOn` (Date), `cover` (Asset), `author` (Reference to `author`), `topics` (Taxonomy terms) | Has an address under `/journal`, appears in lists, and the list cards need the excerpt, date and cover |
| `author` | `bio` (Rich text), `photo` (Asset) | Exists on its own and is shared by many posts |

**Components:**

| Key | Fields | Why |
| --- | --- | --- |
| `text` | `text` (Rich text) | Most of a post is running text |
| `textSection` | `heading` (Text), `level` (Select: `h2`, `h3`), `text` (Rich text) | A section with its own heading, for longer posts |
| `imageBlock` | `image` (Asset), `caption` (Text) | Images between paragraphs. Rich text cannot hold images. |
| `gearList` | `heading` (Text), `items` (Components slot allowing `gearItem`) | A packing list, with items that belong to it |
| `gearItem` | `name` (Text), `link` (Link) | One item, linking to its gear page. Only allowed inside a gear list. |

**Elsewhere:** a `topics` taxonomy with terms such as `hiking` and `paddling`, a shared section for the newsletter sign-up at the end of posts, and global `header` and `footer` entries.

A post body in the delivery API then looks like this:

```json
[
  { "type": "text", "fields": { "text": "<p>Lofoten in January has four hours of light.</p>" } },
  { "type": "imageBlock", "fields": { "image": { "url": "https://…/ridge.webp", "alt": "A ridge above Tromsø" }, "caption": "Above Tromsø" } },
  { "type": "gearList", "fields": { "heading": "What we bring", "items": [{ "type": "gearItem", "fields": { "name": "Fjell GTX boot", "link": { "href": "/gear/fjell-gtx-boot" } } }] } }
]
```

[Schema as code](https://docs.bifrostorbit.com/cms/developers/schema-as-code/) creates exactly this model from a script.

## Rules of thumb

- **Name things for what they are, not how they look.** `gearList`, not `threeColumnGrid`. Looks change; meaning does not.
- **Keys are for ever.** A field's key cannot be renamed, because entries store their values against it. Pick it carefully.
- **Few, flexible components beat many narrow ones.** A `textSection` with a heading level serves more pages than `introSection`, `outroSection` and `sidebarSection`.
- **Required means required to publish.** Drafts can be saved with required fields empty, so editors are never blocked mid-edit.
- **Decide where the main heading comes from.** Each page needs one H1. See [Design components and sections](https://docs.bifrostorbit.com/cms/developers/design-components/).
- **Images go in Asset fields, never in rich text.** Rich text keeps headings, lists, links and tables, and removes images, so put them in a block such as `imageBlock`.
