Blocks & Layouts

Turn Copilot into a page builder – generate structured content for built-in and custom blocks with schema-aware AI and real-time streaming.

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.

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 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. Copilot resolves the inner field's block definitions and inlines them into the parent block's schema. 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. This is by design: it prevents unbounded schema growth that would exceed limitations of AI 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.

Page References

Reference other Kirby pages in your prompt to give the AI cross-page context for more informed content generation.

Quick Reference

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