# Writing for Structured Content

> Source: https://agilitycms.com/docs/editors/writing-for-structured-content

In Agility, content is stored in **fields**, not on a page. A blog post isn't one long document; it's a title, a summary, an author, a date, an image and a body, each in its own field defined by a **content model**. Your website, and any app or channel your developers connect, decides how those fields look.

That changes how you write. You aren't designing a page; you're filling in pieces that may appear in several places, in several layouts, some of which don't exist yet. This article covers the habits that make structured content work.

If the terms are new, start with [Intro to Content for Editors](/docs/editors/introduction-to-content) and [Pages vs Content](/docs/editors/pages-vs-content).

## The rules

### 1. Write for the field, not the page

Every field has a job. Before you write, ask where the field is likely to show up.

| Field | Where it might appear | Write it so that... |
| --- | --- | --- |
| Title | Page heading, listing cards, browser tab, search results, links from other pages | it makes sense on its own, with no surrounding text |
| Summary or description | Listing cards, search results, social shares, email digests | it says what the reader gets, in one or two sentences, without repeating the title |
| Body | The detail page | it can assume the reader has seen the title, but not the summary |
| Image alt text | Screen readers, and in place of the image if it fails to load | it describes what the image shows or does, in context |
| Call to action label | A button | it says what happens next ("Download the guide", not "Click here") |

If you don't know where a field is used, ask your developer, or check the site in **Preview**. A short written note from your developers on what each field is for saves everyone time.

**Named mistake: the summary that is the first paragraph.** Copying the opening paragraph into the summary field makes listings read like truncated articles. Write the summary separately.

### 2. Use fields, not formatting

If something has a meaning, it belongs in a field, not in formatting.

- **A subtitle is a field, not bold text.** Bold text in a rich text field can't be found, reused or styled consistently.
- **A date is a date field, not words.** "Next Tuesday" can't be sorted, filtered or scheduled; a date can.
- **A choice is a drop-down, not free text.** "Webinar", "webinar" and "Webinars" are three different values to a filter.
- **One thing per field.** A field that holds "Price: $49, Duration: 2 hours" can't be shown as two facts in a comparison table.
- **Don't build layout in rich text.** Columns made with tables, spacer lines and manual colors break on mobile and in other channels. Layout is your site's job, through components and page models.

**Named mistake: the field you wish you had.** When you find yourself repeating the same workaround (always bolding the first line, always pasting the same disclaimer), that's a request to change the content model. Raise it with whoever owns your models.

### 3. Write once, link it everywhere

The biggest advantage of structured content is reuse. If the same text appears in two places, it should usually live in one item that both places link to.

- **Shared content lives in the Content area.** Authors, testimonials, product facts, office addresses and disclaimers are good candidates for a content list that pages and other items link to.
- **Change it once, and every place that links to it changes too.** That is the point, and it is also the risk: edit shared content knowing it shows up elsewhere.
- **Page-specific content can live in the component.** A one-off hero heading doesn't need its own content item.

See [Components with Content that is shared across your site](/docs/editors/components-with-content-that-is-shared-across-your-site) and [Reusing Content across Multiple Web Properties](/docs/editors/reusing-content-across-multiple-web-properties).

**Named mistake: copy and paste.** Two copies of the same facts drift apart the first time someone updates only one. Link instead of copying.

> [!NOTE]
> When you publish a page or content item, its **nested** linked content is published with it by default (shared linked content is not). If you edited a nested item but aren't ready for it to go live, tick **Publish this item only** in the Publish prompt. See [Previewing, Publishing, and Content States](/docs/editors/preview-and-publishing).

### 4. Write in a channel-neutral way

The same item may appear on a desktop page, a phone, a listing card and somewhere else your team adds later.

- **Avoid position words.** "See the chart on the right" and "click the button below" are wrong as soon as the layout changes. Name the thing instead.
- **Don't rely on the page around it.** A summary shown in search results has no heading above it.
- **Keep links meaningful.** Link text should make sense when read on its own, which also helps accessibility.

### 5. Keep rich text for prose

Rich text fields are for flowing text: paragraphs, lists, links and the occasional image or table of data.

- **Use real headings, in order.** Pick heading levels by structure, not by how big they look. Don't skip levels.
- **Use real lists** rather than lines that start with a dash.
- **Check what you paste.** The [Rich Text Editor](/docs/editors/rich-text-editor) keeps formatting when you paste from Word and other editors. That saves time, but it can also bring in formatting you don't want. Preview the result.

### 6. Fill in the fields search engines and readers rely on

- **Pages** have built-in SEO fields such as **Page Title** and **Meta Description**. See [Managing SEO for Editors](/docs/editors/manage-seo).
- **Content items** that become their own pages, such as blog posts, often have SEO fields your developers added to the model.
- **Images** need alt text. Your developers can set an image field to require it. See [Accessible Content Checklist for Editors](/docs/editors/accessible-content-checklist).

### 7. Respect what's shared across locales

If your site has more than one locale, some fields may be marked **Constant across all languages** by your developers. Those values are shared by every locale on purpose, so change them knowing it affects every language. See [Working with Localized Content](/docs/editors/working-with-localized-content).

## A quick self-check before you request approval

- [ ] The title makes sense on its own.
- [ ] The summary is written for this field, not copied from the body.
- [ ] Nothing that has a meaning is expressed only as formatting.
- [ ] Shared facts are linked, not pasted.
- [ ] Headings are in order and links make sense out of context.
- [ ] SEO fields and image alt text are filled in.
- [ ] You've checked it in **Preview**.

## For whoever designs the models

Writers can only follow these rules if the content model lets them. If you design content models, see [Content Modeling Strategy](/docs/training-guide/architect-content-strategy) and [Content Models](/docs/developers/content-models) for how to choose fields, lists and relationships.

## Related articles

- [Intro to Content for Editors](/docs/editors/introduction-to-content)
- [Pages vs Content](/docs/editors/pages-vs-content)
- [Accessible Content Checklist for Editors](/docs/editors/accessible-content-checklist)
- [A Content Operations Playbook](/docs/editors/content-operations-playbook)
- [Managing SEO for Editors](/docs/editors/manage-seo)