---
title: "Blocks & Layouts"
description: "Turn Copilot into a page builder – generate structured content for built-in and custom blocks with schema-aware AI and real-time streaming."
canonical_url: "https://kirby.tools/docs/copilot/advanced/blocks-and-layouts"
---

# 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.

<prose-video height="540" poster="/screencasts/kirby-copilot-generate-layouts-poster.jpg" src="/screencasts/kirby-copilot-generate-layouts.mp4" width="908">



</prose-video>

<tip>

If you want to exclude certain blocks, such as custom forms or other content-less block types, you can use the [`excludedBlocks`](/docs/copilot/configuration/global#excludedblocks) configuration option. This allows you to fine-tune which blocks Copilot should generate content for.

</tip>

## How It Works

<steps level="3">

### 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.

</steps>

<tip>

We recommend **Google Gemini** models for blocks and layouts generation, since OpenAI's models have [limitations on nested structured outputs](https://platform.openai.com/docs/guides/structured-outputs#objects-have-limitations-on-nesting-depth-and-size). Gemini models have superior structured output capabilities.

</tip>

## 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.

```yaml [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.

<note>

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.

</note>

## 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**: 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.

---

Every page of this site as Markdown: <https://kirby.tools/sitemap.md>