Models & Blocks

Models define content types. Blocks define reusable chunks that editors place inside a blocks field or rich text field.

When to create a model

Create a model when something exists as its own content item:

• article
• page
• author
• tour
• doc-page
• category

Models fit content that needs:

• its own route
• publishing state
• references from other entries
• lookups by slug or other fields
• list pages or summaries

When to create a block

Create a block when something is a reusable content section:

• hero
• quote
• callout
• FAQ item
• gallery
• pricing row

Blocks fit content that:

• lives inside another entry
• is reordered visually
• is reused across several models
• does not need its own route or publish lifecycle

Pattern

Use models for content items and blocks for sections.

Examples:

• tour model
• tour-guide model
• hero-block
• faq-block
• gallery-block

Blocks field vs rich text field

blocks

Use a blocks field for structured page building:

• landing pages
• modular homepages
• marketing sections
• layouts with clear block boundaries

richtext

Use richtext for editorial flow:

• articles
• journals
• docs
• long-form storytelling

Rich text can still include:

• inline content links
• embedded assets
• embedded blocks

Field groups and tabs

Models stay easier to edit when fields are grouped.

Common groups:

• Content
• SEO
• Metadata
• Settings

A field group can also become its own tab, which keeps large models easier to scan.

Example model

{
  "id": "article",
  "label": "Article",
  "displayField": "title",
  "fields": {
    "title": { "type": "text", "translatable": true, "required": true },
    "slug": { "type": "slug", "sourceField": "title", "required": true },
    "excerpt": { "type": "text", "translatable": true },
    "coverImage": { "type": "asset" },
    "author": { "type": "reference", "model": "author" },
    "content": {
      "type": "richtext",
      "translatable": true,
      "allowedBlocks": ["callout-block", "quote-block"],
      "allowedModels": ["article"]
    }
  }
}

Example block

{
  "id": "hero-block",
  "label": "Hero",
  "fields": {
    "heading": { "type": "text", "translatable": true, "required": true },
    "subheading": { "type": "text", "translatable": true },
    "image": { "type": "asset" },
    "ctaLabel": { "type": "text", "translatable": true },
    "ctaLink": { "type": "link", "models": ["page", "article"] }
  }
}

Rule of thumb

• choose a model when the item is found, routed, or referenced directly
• choose a block when the item is presentation inside another piece of content