Bolt CMS ContentTypes & Fields Standard
Defining ContentTypes in Bolt CMS (config/bolt/contenttypes.yaml) controls the data architecture, admin editing interface, and database relationships of your website. Failing to follow Bolt CMS architectural conventions can lead to uneditable records, broken singletons, layout regressions, or localization errors.
This skill provides the official standards, required rules, and an automated verification script for creating, refactoring, and validating Bolt CMS ContentTypes.
The Golden Rules of Bolt ContentTypes
1. Rich Text: Never Use type: html
[!WARNING] Do NOT use
type: html.
- Why: In Bolt CMS 6,
type: htmlis a generic WYSIWYG HTML field (Trumbowyg editor in the admin) that accepts arbitrary markup, including inline styles and pasted HTML from other sites, and can even allow Twig (allow_twig). Content entered there drifts from the theme's design system and breaks layouts.redactor(andarticlefor long-form content) give editors a controlled toolbar whose output the theme styles through.cms-redactor/.cms-article, and keep all rich-text fields consistent. - Standard Rich Text (
type: redactor): Usetype: redactor(provided bybolt/redactor) for standard editorial rich text: introductions, body copy, descriptions, teasers, and sections. - Structured Long-Form Content (
type: article): Usetype: article(provided bybolt/article) for complex, long-form editorial content (such as blog posts, case studies, news articles) where authors construct articles with imperavi modular blocks (headings, quotes, media embeds, multi-column snippets). - Structured Repeating Data:
If content has discrete fields (e.g., FAQ questions/answers, team members, timeline items), do not ask editors to format HTML. Model them cleanly with
type: collectionandtype: set.
# ❌ INCORRECT (Do not use raw html)
content:
type: html
height: 300px
# ✅ CORRECT for standard body/intro copy
introduction:
type: redactor
sanitise: true
label: "Úvodní text"
localize: true
# ✅ CORRECT for structured long-form articles
body:
type: article
sanitise: true
label: "Obsah článku"
required: true
localize: true2. Singleton ContentTypes: Always Add order: -id
[!IMPORTANT] Official Bolt Documentation: Making a Singleton ContentType recommends
sort: -id(the older name oforder).
House rule: every ContentType withsingleton: trueMUST declareorder: -id.
- Why: In Bolt CMS, setting
singleton: truelimits backend editors to one record in the admin panel. However, when fetched in Twig templates via{% setcontent page = 'homepage' %}or{% setcontent settings = 'settings' %}, Bolt queries the database table. If records have been created, deleted, or re-saved over time, auto-incremented database IDs increase. Bolt's default order is-createdAt, which depends on an editable date;order: -idmakes Bolt always return the most recently created record (highest ID), regardless of how dates were edited, so stale records are never fetched.
A. Routable Singletons (e.g. Homepage)
Singletons that serve a dedicated front-end route:
homepage:
name: Domovská stránka
singular_name: Domovská stránka
singleton: true
order: -id # <-- MANDATORY
viewless: false
record_template: index.twig
locales: [ 'cs', 'en' ]
fields:
<<: [ *common_fields, *seo_field ]
hero_title:
type: text
localize: true
required: trueB. Data Container / Settings Singletons (e.g. Site Settings, Footer, Contact Info)
Singletons that only supply data to templates across the site and do NOT have their own URL route:
- Set
viewless: true(disables single-record public URL/settings/1) default_status: publishedandsearchable: falseare what Bolt already defaults to here (ContentTypesParser:default_statusfalls back topublished,searchableto! viewless). Write them anyway, so the intent is visible in the file.
site_settings:
name: Nastavení webu
singular_name: Nastavení webu
singleton: true
order: -id # <-- MANDATORY
viewless: true # No standalone public route
default_status: published # Automatically published
searchable: false
locales: [ 'cs', 'en' ]
fields:
company_name:
type: text
required: true
contact_email:
type: email
required: true
phone:
type: text3. Resource & Block ContentTypes
[!NOTE] Official Bolt Documentation: Making a Resource ContentType
Resource ContentTypes store reusable snippets, 404 page content, header teasers, or sidebar callouts that are loaded into other templates via {% setcontent block = 'blocks/slug' %}:
- Set
viewless: true - Write
default_status: publishedandsearchable: falseexplicitly (Bolt's defaults for a viewless type, made visible) - Optionally set
show_on_dashboard: falseif editors rarely touch them directly.
blocks:
name: Bloky
singular_name: Blok
viewless: true
default_status: published
searchable: false
show_on_dashboard: false
locales: [ 'cs', 'en' ]
icon_one: "fa:cube"
icon_many: "fa:cubes"
fields:
title:
type: text
required: true
localize: true
slug:
type: slug
uses: [ title ]
content:
type: redactor
sanitise: true
localize: true4. Sets & Collections vs Legacy Repeaters
[!NOTE] Official Bolt Documentation: Transform Bolt 3 repeaters to Bolt 5 sets and collections
In Bolt 6 (as since Bolt 5), the legacy repeater field type is replaced by two distinct field types:
type: set: Groups a fixed composite set of fields together under one parent key (e.g., a button withlabelandhref).type: collection: Allows editors to add, reorder, and remove multiple items (e.g., list of FAQ items, slides, features).
# A repeating list of CTA buttons
buttons:
type: collection
label: "Tlačítka"
fields:
button:
type: set
fields:
label:
type: text
label: "Text tlačítka"
localize: true
required: true
href:
type: text
label: "Odkaz / URL"
required: true
variant:
type: select
values: { primary: "Primární", secondary: "Sekundární" }
default: primary5. Multilingual Parity: Shared vs. Translated Fields
[!CAUTION] In a ContentType with
locales: [...], every field a visitor reads as text (text,textarea,markdown,redactor,article, and theseofield) MUST declarelocalize: true. Fields that hold the same value in every language — images, dates, numbers, selects, URLs, e-mails, phone numbers — stay non-localized.Why? A non-localized field has one value for all languages. The editor shows it on every language tab with the default-locale value, and saving on the English tab writes that one value (
ContentEditController::updateField()stores it under the default locale). An editor who "translates" the title on the English tab silently replaces the Czech title. Nothing fails — the damage shows only on the live site.
Ensure multilingual ContentTypes adhere to:
locales: [ ... ]only contains codes registered inconfig/services.yaml(app_locales).- Text fields declare
localize: true; shared values do not. localize: truewithoutlocaleson the ContentType does nothing — addlocales(Bolt then offers the language tabs).required: trueis independent of this: a required shared field (an image) is filled once for all languages, a required localized field once per language.
6. DRY Architecture with YAML Anchors (__nodes)
Bolt's ContentType parser (src/Configuration/Parser/ContentTypesParser.php) explicitly ignores any top-level YAML keys starting with double underscores __.
Define reusable field clusters under __nodes and compose them into ContentTypes using the YAML merge syntax (<<: [ *common_fields, *seo_field ]):
The seo field type comes from the appolodev/bolt-seo extension (bolt-extension-setup); without it installed, Bolt renders the field as a plain text input.
__nodes:
common_fields: &common_fields
title:
type: text
group: meta
label: "Název / Title"
localize: true
required: true
slug:
type: slug
uses: [ title ]
group: meta
seo_field: &seo_field
seo:
type: seo
group: seo
localize: true
image_field: &image_field
image:
type: image
label: "Hlavní obrázek"
group: content7. Rich Text Is Sanitised: sanitise: true, Never allow_twig
[!IMPORTANT] Every
redactorandarticlefield MUST declaresanitise: true. No field may setallow_twig: true, and no field may switch cleaning off withsanitise: false.
- Why
sanitise: Bolt cleans HTML through its HTML cleaner (htmlcleanerinconfig/bolt/config.yaml, HTMLPurifier) only for fields withsanitise: true. Bolt turns it on by default fortext,textarea,htmlandmarkdown— but not forredactorandarticle, which render their stored HTML unescaped. Without it, any editor (or a stolen editor account) can store<script>oronerror=in content and run it in every visitor's browser, including an administrator's (stored XSS). Cleaning happens on output, so existing content is covered as soon as the option is set. - What changes on the page: nothing editors use. On a real project the only differences were
×in thumbnail URLs being percent-encoded (still valid), Redactor's internaldata-imageattribute being removed, and images without alternative text getting the file name asalt. Embedded iframes are removed wheniframeis not inhtmlcleaner.allowed_tags(bolt-security-hardeningremoves it — embeds go through_consent-embed.twig); whereiframestays allowed, the cleaner dropsallowfullscreen(seebolt-security-hardeningStep 4 for the template fix). - Why never
allow_twig: it renders field content as a Twig template on the server. Whoever can edit the field can then run template code — read configuration, call functions — so an editor account becomes control of the site.
# ✅ CORRECT
body:
type: redactor
sanitise: true
localize: true
# ❌ INCORRECT — rendered unescaped, and as a server-side template
body:
type: redactor
allow_twig: trueWith YAML anchors, put sanitise: true into the shared field node so every ContentType inherits it.
8. Never Use a Reserved Field Name
[!CAUTION] Twig resolves
{{ record.icon }}to a method of Bolt'sContententity (getIcon(),getStatus(),getAuthor(), …) before it looks for a field. A field named after one of them is unreachable in templates or silently returns the wrong value. Bolt's admin dashboard warns about some of them in the Bolt Configuration Notices box ("A field with name icon was found inside the homepage ContentType. You may not be able to access a field with that name in Twig.").
Reserved at the top level, in collections and inside sets (compared lowercase):
array, author, authorname, cachekey, contenttype, createdat, defaultlocale, definition, definitionfromcontenttypeconfig, depublishedat, extras, field, fielddefined, fields, fieldvalue, fieldvalues, icon, id, listformat, locales, modifiedat, publishedat, rawfields, status, statuses, taxonomies, taxonomydefined, taxonomyvalues, toarray, twig.
Also reserved inside a set — each item is a SetField, so item.value calls getValue(), not your sub-field:
allowempty, apivalue, content, contentselect, count, current, currentlocale, defaultlocale, defaultvalue, definition, get, id, key, label, length, locale, name, new, newtranslations, next, parent, parsedvalue, rewind, set, sortorder, translatable, translations, twigvalue, type, usedefaultlocale, valid, value, valueforeditor, version.
Sources: Checks::$generalForbiddenFieldNames / $setForbiddenFieldNames of bolt/configuration-notices-widget and the public getters of Bolt\Entity\Content and Bolt\Entity\Field\SetField (bolt/core 6.1). The dashboard widget only checks the set's own name against the set list, so label / value inside a set pass it unnoticed — the verification script catches them. slug is a getter too, but it is Bolt's own slug field and resolves to it. label is reserved by the widget's list, not by a getter: bolt/core 6.1 has no getLabel() on fields, so item.label still reaches the sub-field through Field::__call() and renders today — rename it anyway, as a future getter would silently shadow the value. Renaming a field in use also needs its stored rows renamed (the field name is in the database), or the values disappear from the record.
Rename it to a more specific English name that says what the field is for — the reserved word plus its context (icon_<section>, icon_<feature>, <feature>_label), never a translation into the site language (rule 10):
# ❌ INCORRECT
icon: { type: select, values: { … } }
facts:
type: collection
fields:
fact:
type: set
fields:
label: { type: text } # item.label → SetField method
value: { type: text } # item.value → SetField::getValue()
# ✅ CORRECT
icon_service: { type: select, values: { … } } # icon_<section> / icon_<feature>
facts:
type: collection
fields:
fact:
type: set
fields:
fact_label: { type: text } # <feature>_label
fact_value: { type: text } # <feature>_value9. Always Set slug: Explicitly
Bolt keys ContentTypes by their slug, and without slug: it slugifies the name — not the YAML key. homepage: with name: Úvod becomes uvod: {% setcontent page = 'homepage' %} throws "no ContentType by that name/slug exists", homepage: homepage in config.yaml finds nothing, config.get('contenttypes/homepage/…') is empty, and the listing route answers at /uvod. Bolt's dashboard reports it as "There is an ambiguity in the slug of the … ContentType".
homepage:
name: Úvod # Czech admin label
singular_name: Úvod
slug: homepage # the key templates and config use
singular_slug: homepage # otherwise /uvod also routes to the recordFor a singleton page the slug is its URL (/{slug} forwards to the record), so pick the public path (slug: podminky-sluzby) and query it by that slug.
10. All Configuration in English
ContentType keys, field names, set and collection item names, select values (the keys of values:), order: fields and template paths are English, also on a Czech-only site — one consistent vocabulary for templates, translations, other projects and other developers. Only what editors and visitors read is in the site language: name, singular_name, field labels, select value labels, and the slugs that are public URLs.
# ❌ INCORRECT — Czech identifiers mixed with English ones
sluzby:
fields:
ikona: { type: select, values: { hlavni: "Hlavní služby" } }
poradi: { type: number }
# ✅ CORRECT — English identifiers, Czech labels and URL
services_page:
name: Služby # admin label (Czech)
slug: sluzby # public URL /sluzby (Czech)
record_template: pages/services_page/services_page.twig
fields:
icon_service:
type: select
label: "Ikona" # admin label (Czech)
values: { main: "Hlavní služby" } # English value, Czech label
position:
type: number
label: "Pořadí"When a reserved name (rule 8) has to be avoided, pick a contextual English name (icon_service, fact_label), not the site-language word. The verification fails on identifiers with non-ASCII characters (diacritics); transliterated words (ikona, poradi) still need a review.
11. Admin Icons: Only Font Awesome Solid Icons Bolt Bundles
icon_one and icon_many are the only icons a ContentType configures in the admin. Bolt turns fa:<name> into <i class="fas fa-<name>">: always the solid style of the Font Awesome Free version bundled in bolt/assets, which is 5.15.4 in Bolt 6.1. The version is printed at the top of public/assets/52.css. Any other name renders as an empty box:
- Font Awesome 6 / 7 names that the current docs and most examples use:
sliders(5:sliders-h),screwdriver-wrench(5:tools),house(home),gear(cog),pen-to-square(edit),file-lines(file-alt),xmark(times),magnifying-glass(search),gauge-high(tachometer-alt). Since FA 6, 356 icons have a different name. - Brand icons (
facebook,whatsapp,google) —fabonly, so they have no solid glyph. - Style prefixes or extra classes in the value (
fas fa-home,fa:home fa-spin) — Bolt addsfasitself and strips everyfa-, so the class breaks.
| Where it renders | Option |
|---|---|
Sidebar and toolbar menu (<admin-sidebar :menu>, <admin-toolbar :menu>), dashboard rows |
icon_many |
Listing heading, edit and new page headings (icon(record)), sidebar submenu items (recent records, "new") |
icon_one (falls back to icon_many) |
Without either option, Bolt shows fa-file / fa-copy, so every such type looks the same. Set both on every ContentType. Pick icons only from the bundled set:
# Icons that render in this project's admin, searchable by name, newer FA name or meaning
php vendor/tomvondracek/bolt-skills/skills/bolt-contenttypes/scripts/admin-icons.php list car
php vendor/tomvondracek/bolt-skills/skills/bolt-contenttypes/scripts/admin-icons.php list settings# ❌ INCORRECT — Font Awesome 6 names, empty boxes in Bolt 6.1
settings:
icon_one: "fa:sliders"
icon_many: "fa:sliders"
services:
icon_one: "fa:screwdriver-wrench"
# ✅ CORRECT — the Font Awesome 5.15.4 solid names
settings:
icon_one: "fa:sliders-h"
icon_many: "fa:sliders-h"
services:
icon_one: "fa:tools"
icon_many: "fa:tools"The list comes from references/fontawesome-5.15.4-solid.tsv: 1,002 solid icons, each with its newer names and search terms, generated from Font Awesome's own metadata/icons.yml. Bolt's bundled fa-solid-900 font is byte-identical to the one in @fortawesome/fontawesome-free@5.15.4. When a Bolt upgrade ships another Font Awesome version, the verification warns, and you generate the list for that version:
npm pack @fortawesome/fontawesome-free@<version> @fortawesome/fontawesome-free@6 @fortawesome/fontawesome-free@7
# unpack each, then (from a Bolt project, for symfony/yaml):
php …/admin-icons.php generate --version=<version> <version>/metadata/icons.yml 6.x/metadata/icons.yml 7.x/metadata/icons.ymlRendered check. verify.sh checks the configuration. After content entry (or any change to icon_one / icon_many followed by cache:clear), confirm in the logged-in admin that every icon renders on every page. Run scripts/admin-icons-browser.js in the browser console, or in a browser automation tool's JavaScript runner, on any /bolt/ page. It loads the dashboard and every content listing, edit and new page linked from the sidebar (GET only). It checks both the server-rendered icons and the icons that the Vue menus and listings receive as JSON. It returns { fontAwesome, pages, icons, missing, errors }, and missing and errors must be empty. It catches icons from any source, also from extensions and from Bolt itself.
Before Entering Content: Bolt Configuration Notices Must Be Clean
Every notice in the Bolt Configuration Notices box of the admin dashboard is a configuration problem that content entered now would inherit (records saved under a wrong slug, values in a field Twig cannot read). Run the same checks from the command line and resolve every warning before the first record is created, and again after every change to contenttypes.yaml:
php vendor/tomvondracek/bolt-skills/skills/bolt-build/scripts/config-notices.php --project=.
# exit 0: clean · exit 1: notices to resolve · exit 2: could not runscripts/verify.sh runs it as its fourth section. Renaming a field after content exists loses that field's values (Bolt stores fields by name), so this check belongs before content entry, not after.
Verification & Automated Linting
To inspect your ContentTypes configuration against all aforementioned standards, run the verification script:
vendor/tomvondracek/bolt-skills/skills/bolt-contenttypes/scripts/verify.shThe rules are checked by scripts/check-contenttypes.php on the parsed YAML (merge keys and tags resolved), so formatting and anchors do not matter.
What the script validates:
- YAML Syntax: Executes
bin/console lint:yaml config/bolt/contenttypes.yaml --parse-tags. - Forbidden
htmlFields: Recursively flags any field, set, or collection usingtype: htmland suggestsredactororarticle. - Singleton Ordering: Flags any
singleton: trueContentType missingorder: -id. - Deprecated
repeater: Flags legacytype: repeaterand advises migrating tocollection+set. - Shared vs. Translated Fields (warning): Flags text fields (
text,textarea,html,markdown,redactor,article) withoutlocalize: truein multilingual ContentTypes. Fields whose name marks a shared value (…url,…link,…email,…phone,ico,dic, social network names) are skipped. Also warns when fields arelocalize: truebut the ContentType has nolocales. - Valid Slugs: Verifies that every
type: slugfield defines theusesmapping when its ContentType has a text field to generate it from (a slug the editors type — a year, a code — next to no text field is fine). - Permitted Locales: Verifies ContentType
localesare declared inapp_locales. - Sanitised Rich Text: Flags
redactorandarticlefields withoutsanitise: true, anyallow_twig: true, andsanitise: falseon any field. - Reserved Field Names: Fails on any field (top level, collection item, set sub-field) named after a method of Bolt's
Contententity, and on set sub-fields named after aSetFieldmethod (rule 8). - Explicit Slug: Fails when a ContentType has no
slug:and the slug Bolt infers fromnamediffers from its key (rule 9). - Bolt Configuration Notices: Runs
bolt-build/scripts/config-notices.php— the dashboard widget's checks — and fails on any warning or danger notice. - English Identifiers: Fails on ContentType keys, field names and select values containing non-ASCII characters (rule 10).
- Admin Icons:
scripts/admin-icons.php checkreads the Font Awesome version and icon classes from Bolt's admin CSS (public/assets/*.css). It fails on anicon_one/icon_manythat is notfa:<name>, that has no class (Font Awesome 6 / 7 names, typos), or that has no solid glyph (brand icons), and names the 5.15.4 replacement. It warns on a ContentType without icons, or when no list exists for the bundled version (rule 11).
Complete Reference Template
Here is a complete, production-ready blueprint demonstrating all rules together:
# config/bolt/contenttypes.yaml
__nodes:
common_fields: &common_fields
title:
type: text
group: meta
label: "Název"
localize: true
required: true
slug:
type: slug
uses: [ title ]
group: meta
seo_field: &seo_field
seo:
type: seo
group: seo
localize: true
# 1. Routable Singleton
homepage:
name: Domovská stránka
singular_name: Domovská stránka
singleton: true
order: -id
viewless: false
record_template: index.twig
locales: [ 'cs', 'en' ]
fields:
<<: [ *common_fields, *seo_field ]
hero_title:
type: text
localize: true
required: true
hero_intro:
type: redactor
sanitise: true
localize: true
# 2. Viewless Settings Singleton
settings:
name: Nastavení webu
singular_name: Nastavení webu
singleton: true
order: -id
viewless: true
default_status: published
searchable: false
locales: [ 'cs', 'en' ]
fields:
phone:
type: text
email:
type: email
# 3. Viewless Reusable Blocks
blocks:
name: Bloky
singular_name: Blok
viewless: true
default_status: published
searchable: false
show_on_dashboard: false
locales: [ 'cs', 'en' ]
fields:
<<: [ *common_fields ]
content:
type: redactor
sanitise: true
localize: true
# 4. Standard Routable Articles with Redactor & Article
articles:
name: Články
singular_name: Článek
locales: [ 'cs', 'en' ]
listing_template: pages/articles/articles.twig # pages/<name>/<name>.twig (Integration Contract)
record_template: pages/articles/articles.record.twig # pages/<name>/<name>.record.twig
order: -createdAt
fields:
<<: [ *common_fields, *seo_field ]
teaser:
type: redactor
sanitise: true
label: "Perex článku"
localize: true
body:
type: article
sanitise: true
label: "Obsah článku"
localize: true
required: true