View Button & Section Configuration

Configure Copilot view buttons and sections in your blueprints with fine-grained control over AI generation behavior.

Kirby Copilot supports configuration through view buttons (in Kirby 5+) and sections, giving you fine-grained control over AI generation behavior. Both approaches support the same configuration options and can be used together.

View Button Configuration

View buttons are available in Kirby 5+ only. For earlier versions, use the Copilot section approach.

In Kirby 5, you can add the Copilot view button to any blueprint and configure its behavior with props:

buttons:
  copilot:
    label: AI Assistant
    userPrompt: Generate content based on the site structure and existing content
    theme: blue-icon
  preview: true
  languages: true

buttons:
  copilot:
    label: AI Assistant
    userPrompt: "Create engaging content for this page about {title}"
    theme: blue-icon
  preview: true
  settings: true
  languages: true
  status: true

buttons:
  copilot:
    label: AI Assistant
    userPrompt: Analyze this file and suggest descriptive content
    theme: blue-icon
  preview: true
  settings: true
  languages: true

The view button opens a prompt dialog that allows you to generate content for multiple fields at once:

Section Configuration

Add the Copilot section to any blueprint for field-specific AI generation:

sections:
  copilot:
    type: copilot
    field: content

sections:
  copilot:
    type: copilot
    label: Content Generator
    field: blocks
    userPrompt: "Write a comprehensive article about {title} with multiple sections"
    theme: positive
    size: lg
    help: Use this to generate initial content drafts for your blocks field.

The section provides a dedicated interface for generating content for a specific field:

Available Options

When configured globally, these options will apply to both view buttons and sections. Local configurations can override them.

`label` String

Custom label for the view button or section. The default depends on the Panel language (e.g., "Copilot" for English).

buttons:
  copilot:
    label: AI Assistant

sections:
  copilot:
    type: copilot
    field: content
    label: Content Generator

`userPrompt` String

Default user prompt that appears when the generation dialog opens (view button) or when the section is rendered. Without a predefined prompt, the input field will be empty. Users can edit the prompt before generating content.

buttons:
  copilot:
    userPrompt: Create engaging content for this page about {title}

sections:
  copilot:
    type: copilot
    field: metaDescription
    userPrompt: |
      Generate a SEO meta description in 140 characters max for my article "{title}":
      {text}

With this configuration, the section will render as follows:

Copilot section with predefined user prompt

Edits to the prompt in the section are stored to the local storage of the user's browser.

Check out the editable property to disable the editing of the user prompt.

Kirby Query Language
In Copilot sections, you can use queries to set the user prompt dynamically. This is useful for dynamic prompts based on page's content.

sections:
  copilot:
    userPrompt: "{{ page.customPrompt.value }}"

`systemPrompt` String

Custom system prompt that controls how the AI structures and formats the generated content. Users cannot see or edit this prompt.

Defaults to the global systemPrompt if not set locally in the view button or section.

buttons:
  copilot:
    systemPrompt: You are a technical writer specializing in documentation. Use clear, concise language.

sections:
  copilot:
    type: copilot
    field: content
    systemPrompt: You are an expert copywriter. Create engaging, conversion-focused content.

Learn more about the system prompt and how to customize it effectively.

For Copilot sections, Kirby queries are supported just as in the userPrompt property.

`icon` String

Custom icon for the view button or section.

Default: sparklingOptions: Any of the default Kirby Panel icons or a custom icon like copilot-ai-generate.

buttons:
  copilot:
    icon: copilot-ai-generate
    theme: blue-icon

sections:
  copilot:
    type: copilot
    icon: copilot-ai-generate
    theme: blue-icon

`theme` String

Default: notice-iconOptions: notice-icon, passive, white, info, positive, warning, notice, negative, *-icon variants (e.g., positive-icon, negative-icon)

buttons:
  copilot:
    theme: blue-icon

sections:
  copilot:
    type: copilot
    field: content
    theme: blue-icon

`logLevel` String

Set the logging level for debugging AI generation. Inspect the browser console to see logs.

Options: error, warn, info, debug

buttons:
  copilot:
    logLevel: info

sections:
  copilot:
    type: copilot
    field: content
    logLevel: debug

Section-Only Options

The following options are only available for sections (not view buttons):

`field` String

Required for sections. Specifies which field to generate content for. This should be the name of a field defined in the same blueprint.

sections/copilot.yml

type: copilot
field: blocks

`editable` Boolean

Control whether users can edit the prompt. Setting it to false is useful if a specific userPrompt should always be used without modifications.

Learn more about working with files on the dedicated Files as Context page.

Default: true

sections/copilot.yml

type: copilot
field: content
userPrompt: Write a technical article about the topic "{title}"
editable: false

Copilot section with immutable user prompt

`files` Boolean | String

Context is key to relevant AI-generated content. This option enables file attachments for providing context to the AI.

Default: trueOptions: true, false, "auto"

To disable file attachments and prevent users from adding files, set the files property to false:

sections/copilot.yml

type: copilot
field: blocks
files: false

Copilot section with files configuration

On a Kirby file page, setting files: auto pre-selects the current file as context for the user prompt. This is useful for generating metadata like alternative text or descriptions based on the image or PDF, that has already been uploaded to the Panel:

sections/copilot.yml

type: copilot
field: alt
# Use the uploaded file as context
files: auto
# Optional: Provide a pre-defined user prompt
userPrompt: Write an alternative text for the provided image. Use a maximum of 10 words.
# Optional: Disable the editing of the user prompt
editable: false

The section above will use the current file of a Kirby file model as context for the user prompt:

`open` Boolean

Set the initial state of the prompt input accordion in sections.

Default: false (closed)

`storage` Boolean

Enable or disable local storage for saving user prompts in the browser. When enabled, prompts are remembered between sessions.

Default: true

sections/copilot.yml

type: copilot
field: content
storage: false

`size` String

Controls the size of buttons (Generate, Undo, Redo) in the Copilot section interface.

Default: mdOptions: xs, sm, md, lg

sections/copilot.yml

type: copilot
field: content
size: lg

`help` String

Provide additional help text or instructions for the Copilot section.

sections/copilot.yml

type: copilot
help: |
  Example: Write a summary of this page and include the contents of {blocks}.

Configuration Precedence

Configuration options are applied in the following order (later options override earlier ones):

Default values (built into the plugin)
Global configuration (in config.php)
View button & section props (in blueprints)

return [
    'johannschopplich.copilot' => [
        'systemPrompt' => 'Default system prompt', // Applied globally
        'theme' => 'positive'
    ]
];

sections:
  copilot:
    type: copilot
    field: content
    theme: blue-icon # Overrides global config
    # systemPrompt inherited from global config

buttons:
  copilot:
    theme: blue-icon # Overrides global config

Global Configuration

Configure AI providers, API keys, models, and global defaults for the Kirby Copilot plugin.

System Prompt

Configure the default system prompt for the AI model.