Index of every page on this site: llms.txt
All skills
vondry avatar

/bolt-contenttypes

@083eb14
Run it yourself

Use this skill whenever you need to create, modify, or validate ContentTypes and fields in Bolt CMS (config/bolt/contenttypes.yaml). Enforces strict best practices: no raw html fields (use redactor or article), sanitise: true on every rich-text field and never allow_twig, mandatory order: -id on singletons, no reserved field names (icon, status, author, … — and label, value, name, type inside sets), an explicit slug on every ContentType, all identifiers in English, admin icons only from the Font Awesome 5.15.4 solid set Bolt bundles (no FA 6 names like sliders or screwdriver-wrench), viewless resource blocks, collection/set structuring, multilingual consistency, and a clean Bolt Configuration Notices check before content.

  • 6 files
  • 114.9 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/vondry/bolt-skills/bolt-contenttypes

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈189 tokens for metadata: the name and description. ≈6.5k when used: this file.

Description uses 9.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈751 characters, or 9.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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: html is 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 (and article for 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): Use type: redactor (provided by bolt/redactor) for standard editorial rich text: introductions, body copy, descriptions, teasers, and sections.
  • Structured Long-Form Content (type: article): Use type: article (provided by bolt/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: collection and type: 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: true

2. Singleton ContentTypes: Always Add order: -id

[!IMPORTANT] Official Bolt Documentation: Making a Singleton ContentType recommends sort: -id (the older name of order).
House rule: every ContentType with singleton: true MUST declare order: -id.

  • Why: In Bolt CMS, setting singleton: true limits 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: -id makes 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: true
B. 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: published and searchable: false are what Bolt already defaults to here (ContentTypesParser: default_status falls back to published, searchable to ! 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: text

3. 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: published and searchable: false explicitly (Bolt's defaults for a viewless type, made visible)
  • Optionally set show_on_dashboard: false if 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: true

4. 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 with label and href).
  • 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: primary

5. 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 the seo field) MUST declare localize: 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:

  1. locales: [ ... ] only contains codes registered in config/services.yaml (app_locales).
  2. Text fields declare localize: true; shared values do not.
  3. localize: true without locales on the ContentType does nothing — add locales (Bolt then offers the language tabs).
  4. required: true is 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: content

7. Rich Text Is Sanitised: sanitise: true, Never allow_twig

[!IMPORTANT] Every redactor and article field MUST declare sanitise: true. No field may set allow_twig: true, and no field may switch cleaning off with sanitise: false.

  • Why sanitise: Bolt cleans HTML through its HTML cleaner (htmlcleaner in config/bolt/config.yaml, HTMLPurifier) only for fields with sanitise: true. Bolt turns it on by default for text, textarea, html and markdown — but not for redactor and article, which render their stored HTML unescaped. Without it, any editor (or a stolen editor account) can store <script> or onerror= 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 internal data-image attribute being removed, and images without alternative text getting the file name as alt. Embedded iframes are removed when iframe is not in htmlcleaner.allowed_tags (bolt-security-hardening removes it — embeds go through _consent-embed.twig); where iframe stays allowed, the cleaner drops allowfullscreen (see bolt-security-hardening Step 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: true

With 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's Content entity (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>_value

9. 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 record

For 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) — fab only, so they have no solid glyph.
  • Style prefixes or extra classes in the value (fas fa-home, fa:home fa-spin) — Bolt adds fas itself and strips every fa-, 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.yml

Rendered 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 run

scripts/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.sh

The 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:

  1. YAML Syntax: Executes bin/console lint:yaml config/bolt/contenttypes.yaml --parse-tags.
  2. Forbidden html Fields: Recursively flags any field, set, or collection using type: html and suggests redactor or article.
  3. Singleton Ordering: Flags any singleton: true ContentType missing order: -id.
  4. Deprecated repeater: Flags legacy type: repeater and advises migrating to collection + set.
  5. Shared vs. Translated Fields (warning): Flags text fields (text, textarea, html, markdown, redactor, article) without localize: true in multilingual ContentTypes. Fields whose name marks a shared value (…url, …link, …email, …phone, ico, dic, social network names) are skipped. Also warns when fields are localize: true but the ContentType has no locales.
  6. Valid Slugs: Verifies that every type: slug field defines the uses mapping 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).
  7. Permitted Locales: Verifies ContentType locales are declared in app_locales.
  8. Sanitised Rich Text: Flags redactor and article fields without sanitise: true, any allow_twig: true, and sanitise: false on any field.
  9. Reserved Field Names: Fails on any field (top level, collection item, set sub-field) named after a method of Bolt's Content entity, and on set sub-fields named after a SetField method (rule 8).
  10. Explicit Slug: Fails when a ContentType has no slug: and the slug Bolt infers from name differs from its key (rule 9).
  11. Bolt Configuration Notices: Runs bolt-build/scripts/config-notices.php — the dashboard widget's checks — and fails on any warning or danger notice.
  12. English Identifiers: Fails on ContentType keys, field names and select values containing non-ASCII characters (rule 10).
  13. Admin Icons: scripts/admin-icons.php check reads the Font Awesome version and icon classes from Bolt's admin CSS (public/assets/*.css). It fails on an icon_one / icon_many that is not fa:<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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 083eb14. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 3 weeks ago

README badge

README badge for vondry/bolt-skills/bolt-contenttypes