michtio/craftcms-claude-skills/craft-content-modeling

Craft CMS 5 — Content Modeling

How to structure content in Craft CMS 5. Sections, entry types, fields, Matrix, relations, asset management, and strategic patterns for real projects.

This skill covers content architecture — what goes in the CP, how it's organized, and how templates access it. For extending Craft with PHP (plugins, modules, custom element types), see the craftcms skill.

Companion Skills — Always Load Together

When this skill triggers, also load:

• `craft-site` — Template architecture, component patterns, routing. Required when content decisions affect how templates render data.
• `craft-twig-guidelines` — Twig coding standards. Required when writing any Twig examples or template code alongside content modeling.
• `ddev` — All commands run through DDEV. Required for running project config commands, Craft CLI, and content migrations.

Documentation

• Entries: https://craftcms.com/docs/5.x/reference/element-types/entries.html
• Sections: https://craftcms.com/docs/5.x/reference/element-types/entries.html#sections
• Fields: https://craftcms.com/docs/5.x/system/fields.html
• Field types: https://craftcms.com/docs/5.x/reference/field-types/
• Matrix: https://craftcms.com/docs/5.x/reference/field-types/matrix.html
• Relations: https://craftcms.com/docs/5.x/system/relations.html
• Eager loading: https://craftcms.com/docs/5.x/development/eager-loading.html
• Project config: https://craftcms.com/docs/5.x/system/project-config.html

Use WebFetch on specific doc pages when a reference file doesn't cover enough detail.

The Craft 5 Mental Model

Everything is becoming an entry. Entry types are global (shared across sections and Matrix fields). Fields come from a global pool. This is the "entrification" of Craft — categories, tags, and globals are being unified into entries over a three-version arc:

• Craft 4.4 — entrify CLI commands added to convert categories, tags, and globals to entries
• Craft 5 — Categories, tags, and global sets are deprecated and discouraged for new projects. New category groups, tag groups, and global sets can still be created in the CP (the "New" buttons remain, gated by allowAdminChanges), and existing ones continue to work. A unified "Content" section replaces the fragmented entries view. Custom entry index pages (5.9.0) solve the sidebar organization concern.
• Craft 6 — Categories, tags, and global sets will be removed entirely

For new projects, always use entries: Structure sections for hierarchical taxonomy, Channel sections for flat taxonomy, Singles for site-wide settings. For existing projects, migrate at your own pace using the entrify commands.

Three decisions define your content architecture:

1. Which section type organizes the content (Single, Channel, Structure)
2. Which entry types define its shape (global, reusable across contexts)
3. Which relation strategy connects content together (Entries fields, Matrix, CKEditor nested entries, or a combination)

CMS Editions

Craft CMS has four editions (Solo, Team, Pro, Enterprise) that affect content modeling. The key distinction: if any section needs multiple custom user groups with per-group edit/view restrictions, you need Pro or Enterprise (multiple custom user groups are Pro+ only). Team includes one fixed "Team" group whose permissions are customizable for non-admins, plus a 5-user cap. See references/users-and-permissions.md for the full editions table and permissions architecture.

Choose the edition before modeling — it determines whether you can scope content access by user group, which affects section and field architecture.

Section Type Decision

Section Properties

Beyond the type, sections have settings that matter for content architecture:

• `maxAuthors` (default 1) — allows multiple authors per entry (new in 5.0.0). Set higher for collaborative content.
• `minAuthors` (default 1, new in 5.10) — minimum number of authors required to save an entry. Set 1 to enforce that every entry has at least one author. Validated on save; setting minAuthors > maxAuthors is rejected by Craft's section validator. Combine with maxAuthors to define an exact range (min: 1, max: 3 = "1 to 3 authors required").
• `enableVersioning` (default true) — version history for entries
• `defaultPlacement` — 'beginning' or 'end' for new entries in structures
• `previewTargets` — array of {label, urlFormat} objects defining where entries can be previewed. Default: primary entry page. Add custom targets for headless frontends, staging URLs, or PDF previews.

Singles replace globals

Set preloadSingles => true in config/general.php to access singles as global Twig variables by handle — identical to the old globals behavior but with drafts, revisions, live preview, and scheduling.

{# With preloadSingles enabled #}
{{ siteSettings.footerText }}
{{ siteSettings.socialLinks.all() }}

Caveat: Singles always propagate to all sites. This is hard-coded.

Structure queries for navigation

{% set topLevel = craft.entries.section('pages').level(1).all() %}
{% set children = craft.entries.descendantOf(entry).descendantDist(1).all() %}
{% set breadcrumbs = craft.entries.ancestorOf(entry).all() %}
{% set siblings = craft.entries.siblingOf(entry).all() %}

Entry Types in Craft 5

Entry types are defined globally (Settings → Entry Types), then attached to sections and Matrix fields. One entry type can serve multiple contexts.

Key implications:

• Changing an entry type's field layout affects every section and Matrix field using it
• Fields come from the global pool — same field definition reused everywhere
• Per-context name/handle/description overrides available (5.6.0+) — useful when the same entry type serves different purposes in different sections
• The global pool demands careful field naming — use specific handles

Entry Type Visual Identity (Craft 5 new)

Entry types have visual properties that improve the editorial experience:

• `icon` — custom icon identifier, shown in entry type selectors and Matrix "+" menus
• `color` — one of 20 options (red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, white, gray, black)
• `description` (5.8.0) — help text explaining what this entry type is for
• `group` (5.8.0) — collapsible grouping in section/Matrix entry type assignments
• `uiLabelFormat` (5.9.0) — customize the label shown in element indexes (default '{title}')
• `hasTitleField` / `titleFormat` — disable the title field and auto-generate from other fields
• `showSlugField` (5.0.0) / `showStatusField` (4.5.0) — hide slug or status from editors
• `allowLineBreaksInTitles` (5.9.0) — for long-form titles

These settings are configured in Settings → Entry Types and affect all contexts where the entry type is used.

Reserved handles — check every proposed field handle against this list

Craft has 83+ reserved handles across all element types via Field::RESERVED_HANDLES. Validation is case-insensitive. Using any of these as a custom field handle will cause a validation error or silent template collision where the native attribute shadows the custom field.

Before proposing any field handle in a content model, check it against the lists below. When a user asks for a field that matches a native attribute name, always use a domain-specific synonym. For example: user says "I need a title field" — the entry already has a native title, so use heading, headline, or pageTitle depending on context.

Most commonly collided (the ones you'll actually try to use):

Full list of reserved handles shared across ALL element types (from Field::RESERVED_HANDLES):

ancestors, archived, attributes, behaviors, canonical, children, contentTable, dateCreated, dateDeleted, dateLastMerged, dateUpdated, descendants, draftId, enabled, enabledForSite, error, errors, fieldLayoutId, fieldValue, fieldValues, firstSave, icon, id, language, level, lft, link, localized, next, nextSibling, owner, parent, parents, prev, prevSibling, ref, revisionId, rgt, root, searchScore, siblings, site, siteId, siteSettingsId, slug, sortOrder, status, structureId, title, trashed, uid, uri, url, viewMode

Additional per-element-type reserved handles:

Also globally reserved (from HandleValidator::$baseReservedWords, applies to ALL handles): attribute, attributeLabels, attributeNames, attributes, dateCreated, dateUpdated, errors, false, fields, handle, id, n, name, no, rules, this, true, uid, y, yes

Field Instances — Reuse Over Duplication

Fields are defined once globally, then instanced into field layouts. Each instance can override four properties without affecting the global definition: