Blocks & Layouts

Generate structured content for built-in and custom blocks and whole layouts, streamed into the field as it arrives.

Kirby Copilot supports generating content for Kirby's blocks and layout fields, including both built-in and custom block types, so a prompt can produce a whole page structure instead of one field.

It accomplishes this by using object generation with JSON schemas, which enables the AI model to generate structured data that matches the block definitions in your project.

Kirby Panel

Luise Frey: Rooms of Silence

Layout ×

No rows yet

If you want to exclude certain blocks, such as custom forms or other content-less block types, you can use the excludedBlocks configuration option. This allows you to fine-tune which blocks Copilot should generate content for.

How It Works

Copilot considers Kirby's built-in blocks, blocks registered by plugins, and custom blocks defined in site/blueprints/blocks/ – limited to the field's fieldsets when the field sets them. Layout columns take their widths from the field's layouts option. Blocks appear in the Panel as they stream in, and generated content is appended to existing field content, not replaced.

Google Gemini models are the recommended choice for blocks and layouts: OpenAI's models cap the nesting depth of structured outputs, and block and layout schemas exceed it. Gemini models do not have that limit.

Block Descriptions

Custom block blueprints support an optional description key. Copilot passes this description to the AI model as part of the block's schema, giving it richer context about the block's purpose and expected content.

site/blueprints/blocks/highlight.yml

name: Highlight
description: A visually prominent section showcasing a key metric or achievement, such as "200+ customers" or "99.9% uptime"
icon: chart
fields:
  number:
    type: text
  label:
    type: text
  description:
    type: writer

Without a description, the schema only includes the block's name. Adding one helps the AI model understand the block's intent and generate more fitting content, especially for project-specific blocks where the name alone is ambiguous.

Nested Blocks

Custom block blueprints that contain a type: blocks field – blocks within blocks – are fully supported. If the inner blocks field specifies a fieldsets option, only those allowed block types will be included.

Nesting depth is capped at one level. Nested blocks cannot themselves contain further nested blocks.

Caveats

Depending on the block's complexity, the resulting JSON schema can become equally complex. This leads to the following caveats:

Schema size: OpenAI has limitations on the nesting depth and size of JSON schemas. If the schema is too large, the AI model will fail to generate a response. In this case, try reducing the number of blocks used in the fieldsets or simplify the block definitions.
Layout generation: layout schemas nest one level deeper than block schemas, so they are the first to hit that limit. The plugin does not restrict the provider – OpenAI models are free to try and will simply fail on schemas they cannot handle. Gemini models are the reliable choice here.

Exceptions

Catch upstream provider failures, missing API keys, and configuration errors with three typed exceptions.

Quick Reference

Keyboard shortcuts, properties, and supported field types at a glance.