Blocks & Layouts

Learn how to generate content for blocks and layout fields.

Kirby Copilot supports generating content for Kirby's blocks and layout fields, including both built-in and custom block types. This makes it a true page builder for Kirby CMS.

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

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

Block Discovery

Copilot discovers all available blocks from Kirby's built-in types, blocks registered by plugins, and custom blocks defined in site/blueprints/blocks/. If the field's fieldsets option limits the available blocks, only those will be considered for generation.

Schema Generation

For each block type, Copilot reads the block's field definitions and generates a schema with appropriate constraints. All block schemas are then combined into a union type. For layouts, additional column structure with width constraints is added to the schema.

AI Request

The schema is sent to the AI provider along with your prompt. The JSON schema format enforces the model to respond with structured data that matches your block definitions.

Streaming Response

The AI streams structured data back in real-time. You'll see blocks and content appear progressively in the Panel as they're generated.

Normalization

Each generated block and layout is normalized before insertion. This includes assigning unique IDs (required by Kirby's block editor) and applying default values like column widths. Generated content is appended to existing field content, not replaced.

We recommend Google Gemini models for blocks and layouts generation, since OpenAI's models have limitations on nested structured outputs. Gemini models have superior structured output capabilities.

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 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: Due to the same limitations of OpenAI, the layout field generation is only supported by models other than OpenAI. Gemini models are recommended for this feature.

File Attachments

Append images and PDF files as context to user prompts.

Quick Reference

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