Brease Docs

Sections

Let editors add, move, duplicate and delete page sections without the AI.

When a site follows the sections convention, editors get a "+" above and below every section in quick edit mode. It opens a list of the site's section types, each with a screenshot. They can also move, duplicate and delete sections. The AI uses the same operations.

The sections folder

Every section type a page can hold is a folder:

src/brease/sections/            (brease/sections/ when the site has no src/)
  index.tsx                     the type → component map; renders content.sections
                                (Sections.astro, or the framework's own file, works too)
  testimonials/
    section.json
    Testimonials.tsx            the component, in the site's framework
section.json
{
  "name": "Testimonials",
  "description": "Three customer quotes",
  "fields": {
    "type": "object",
    "properties": {
      "title": { "type": "string", "maxLength": 80 },
      "layout": { "enum": ["grid", "slider"], "default": "grid" },
      "items": {
        "type": "array",
        "minItems": 3,
        "items": {
          "type": "object",
          "properties": {
            "quote": { "type": "string" },
            "photo": {
              "type": "object",
              "properties": { "assetId": { "type": "string" }, "url": { "type": "string" }, "alt": { "type": "string" } },
              "required": ["assetId", "url"]
            }
          }
        }
      }
    }
  }
}
  • name and description are what editors see in the list.

  • addable: false keeps a type out of the list. Use it for sections that shouldn't be added by hand, for example one that turns a page into an article. Editors can still move and delete them.

  • fields is a JSON Schema of the section's fields. Brease builds new sections from it:

    • text becomes lorem ipsum: a short phrase when maxLength is 120 or less, or the key is a title or label;
    • images (assetId and url) get Brease's placeholder image;
    • links (label with href, url or value, or a string with "format": "uri") get #;
    • rich text ("format": "html", "contentMediaType": "text/html", or a key ending in html) gets a paragraph;
    • a default wins;
    • an enum takes its first value, a switch is false;
    • lists get minItems items, or one.

    The editor also uses the schema to pick each field's control.

  • shared: true gives a type one content for every page that shows it, for example a newsletter signup or a list of courses. See Shared sections.

  • Site-wide parts don't go in the folder. Headers, footers, cookie banners and site-wide content stay where they are.

Content and markup

A page's sections are one list, content.sections:

{
  "template": "page",
  "title": "About us",
  "sections": [
    { "id": "sec_01j…", "type": "testimonials", "title": "What parents say", "items": [ … ] }
  ]
}
  • id and type are reserved keys. type is the folder's name.
  • Every locale of a page holds the same ids, in the same order.
  • Fixed page fields, such as a page title, stay outside the list.

The map file renders the list, and renders nothing for a type it doesn't know:

import { type BreaseSection, sectionAttrs, sectionsAttrs } from 'brease-client'

export function Sections({ sections }: { sections: BreaseSection[] }) {
  return (
    <div {...sectionsAttrs}>
      {sections.map((s, i) => {
        const Component = map[s.type]
        return Component ? <div key={s.id} {...sectionAttrs(s)}><Component section={s} index={i} /></div> : null
      })}
    </div>
  )
}
AttributeOn
data-brease-sections="sections"the element holding the list
data-brease-section="<id>" and data-brease-block="<type>"each section's root
data-brease="sections.<index>.<field>"each field inside a section

If your content.schema.json describes the page templates, declare sections as an array. Brease adds each type's fields to it.

Shared sections

A type with "shared": true keeps its content once, on the site-wide content page (slug _global), under content.shared.<type>. On pages, its item in the list is only a reference:

pages/pg_home/en.json
{ "sections": [ { "id": "sec_01j…", "type": "signup" } ] }
pages/pg_global/en.json
{ "template": "global", "shared": { "signup": { "title": "Join the newsletter", "button": "Sign up" } } }
  • The site's renderer reads a shared type's fields from the site-wide page in the same locale.
  • Its field markers use the other-page prefix: data-brease="<_global pageId>:shared.signup.title".
  • Editing the fields on any page changes them everywhere, and the editor says the content is shared.
  • Adding a shared section to another page adds a reference. Brease creates the content the first time a shared type is added.
  • Deleting a shared section from a page removes only that page's reference.

Checking a site

npx brease-client check

It warns when:

  • there is no map file, or a type is missing from it;
  • a folder's name isn't lowercase letters, numbers and -;
  • a folder has no section.json, or it isn't valid JSON, has no name, or its fields isn't a JSON Schema object;
  • no component renders data-brease-section (or uses sectionAttrs);
  • content in brease-seed/ or .brease/ uses a type without a folder, has a section without an id or type, repeats an id, or isn't a list;
  • a page's locales hold different sections.

It exits with code 1 when there are warnings, so it can run in CI.

Brease runs the same check, and a check for placeholder content, before publishing.

Screenshots

Brease takes a screenshot of each section type for the list. It uses the type's first appearance on the site's pages, and takes a new one when the type's folder changes. A type no page uses yet is listed without one.

On this page