View Button & Field Configuration

Kirby Copilot supports configuration through Panel view buttons and individual writer/textarea fields, providing fine-grained control over AI generation behavior.

View Button Configuration

The Copilot view button can be added to any Panel view (site, page, file, user) alongside the default buttons like the preview button or settings dropdown. Configure its behavior with props in your blueprints:

buttons:
  copilot:
    label: AI Assistant
    userPrompt: Generate homepage content including a headline, intro paragraph, and three key features with descriptions.
    theme: blue-icon
  open: true
  preview: true
  languages: true

buttons:
  copilot:
    label: AI Assistant
    userPrompt: |
      Write a complete landing page for "{title}": a compelling headline, introduction, three benefit sections, and a call-to-action.
    theme: blue-icon
  open: true
  preview: true
  settings: true
  languages: true
  status: true

buttons:
  copilot:
    label: AI Assistant
    userPrompt: Generate image metadata including a descriptive title, alt text, caption, and relevant tags based on the visual content.
    theme: blue-icon
  open: true
  settings: true
  languages: true

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

Available Properties

label String

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

buttons:
  copilot:
    label: AI Assistant

userPrompt String

Default user prompt that appears when the generation dialog opens. Without a predefined prompt, the input field will be empty. Users can edit the prompt before generating content.

buttons:
  copilot:
    userPrompt: 'Write a landing page for "{title}": headline, intro, three benefits, and call-to-action.'

fields:
  text:
    type: writer
    marks:
      - copilot
      - copilot-suggestions
    copilot:
      userPrompt: Write a product description for "{title}". Highlight benefits, not features. Max 200 words.

fields:
  description:
    type: textarea
    buttons:
      - copilot
    copilot:
      userPrompt: Summarize "{title}" in 2-3 sentences. Focus on the main value proposition.

A Kirby query in the view button or the section resolves against the current model, so editors can write the prompt themselves in a field:

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

Note the two syntaxes side by side: {{ ... }} is a Kirby query resolved in the blueprint, while {field} is a placeholder resolved when the prompt is sent.

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 system prompt if not set locally.

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

Kirby queries resolve here too, on the same terms as userPrompt.

icon String

Custom icon for the view button.

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

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

theme String

Controls the visual appearance and color theme of the button.

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

buttons:
  copilot:
    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

Configuration Precedence

Properties are applied in the following order (later values override earlier ones):

1. Default values (built into the plugin)
2. Global configuration (in config.php)
3. View button props (in blueprints)

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

buttons:
  copilot:
    logLevel: debug # Overrides global config
    # systemPrompt inherited from global config