Kirby CMS Developer Toolkit

A comprehensive Visual Studio Code extension that significantly enhances productivity for Kirby CMS developers by providing intelligent code generation, refactoring tools, navigation, type-hints, and Blueprint validation.

Note: This is an unofficial third-party extension and is not affiliated with or endorsed by Kirby CMS.

Features

1. Page Type Scaffolding

Quickly generate complete page types with all necessary files through an interactive wizard.

Features:

🚀 Interactive command palette wizard
📝 Generates Blueprint YAML with sensible defaults
🎨 Creates HTML5 template boilerplate
⚙️ Optional Controller and Model file generation
🔒 Built-in security validation for file names
✨ Automatic type-hint injection in templates
📂 Creates necessary directories automatically

Usage:

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run Kirby: New Page Type
Enter the page type name (e.g., "project", "article")
Select which files to generate:
- Blueprint (Required) - site/blueprints/pages/project.yml
- Template (Required) - site/templates/project.php
- Controller (Optional) - site/controllers/project.php
- Model (Optional) - site/models/project.php
Files are created with sensible defaults and opened automatically

Example Output:

Blueprint (site/blueprints/pages/project.yml):

title: Project

fields:
  title:
    type: text
    label: Title
  text:
    type: textarea
    label: Text

Template (site/templates/project.php):

<?php
/**
 * @var \Kirby\Cms\Page $page
 * @var \Kirby\Cms\Site $site
 * @var \Kirby\Cms\App $kirby
 */
?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title><?= $page->title() ?></title>
</head>
<body>
  <h1><?= $page->title() ?></h1>
  <div><?= $page->text()->kirbytext() ?></div>
</body>
</html>

Model (site/models/project.php):

<?php

use Kirby\Cms\Page;

class ProjectPage extends Page
{
  // Add custom page methods here
}

2. Blueprint/Template Synchronization

Automatically detect missing counterpart files when you create a Blueprint or Template, and offer to create them with one click.

Features:

🔄 Monitors Blueprint and Template file creation in real-time
📝 Prompts to create missing counterparts automatically
⚙️ Optional Controller and Model file creation
🎯 Handles nested Blueprint structures (e.g., blog/post.yml → blog.post.php)
🔕 "Don't ask again" option with workspace-specific memory
⚡ Smart debouncing to avoid notification spam during bulk operations
🛠️ Three behavior modes: Ask (default), Never, Always

How it works:

Scenario 1: Creating a Blueprint

Create a new Blueprint file: site/blueprints/pages/article.yml
Extension detects no matching template exists
Notification appears: "📄 Blueprint 'article.yml' created without a template. Create 'article.php'?"
Choose:
- Create Template - Creates basic template with HTML boilerplate
- Create Template + Controller + Model - Creates all three files
- Don't ask again - Remembers choice for this workspace
- Dismiss - Skip this time only

Scenario 2: Creating a Template

Create a new template file: site/templates/project.php
Extension detects no matching Blueprint exists
Notification appears: "📄 Template 'project.php' created without a Blueprint. Create Blueprint?"
Choose:
- Create Blueprint - Creates Blueprint with sensible field defaults
- Don't ask again - Remembers choice for this workspace
- Dismiss - Skip this time only

Nested Blueprint Support:

site/blueprints/pages/blog/post.yml → site/templates/blog.post.php
site/templates/section.article.php → site/blueprints/pages/section/article.yml

Configuration Options:

{
  "kirby.enableBlueprintTemplateSync": true,       // Master toggle
  "kirby.syncPromptBehavior": "ask",               // "ask" | "never" | "always"
  "kirby.syncCreateController": false,             // Auto-create controller by default
  "kirby.syncCreateModel": false,                  // Auto-create model by default
  "kirby.syncIgnoreFolders": ["test/", "archive/"] // Exclude patterns
}

Behavior Modes:

"ask" (default): Show notification with action buttons
"never": Completely disable sync prompts
"always": Automatically create missing files without prompting

Reset Dismissed Prompts: Run Kirby: Reset Blueprint/Template Sync Prompts to clear all "Don't ask again" choices.

Use Cases:

Quick prototyping: Create Blueprint first, get Template automatically
Consistency enforcement: Never forget to create matching files
Team workflows: Standardize file creation across team members
Bulk operations: Smart debouncing prevents notification spam during git operations

3. Extract to Snippet

Refactor selected code into reusable snippets with automatic replacement.

Features:

✂️ Extract any selected code to a new snippet file
🔄 Automatically replaces selection with snippet() call
🎯 Smart PHP context detection (adds tags only when needed)
📐 Preserves indentation perfectly
🗂️ Supports nested snippet paths (e.g., partials/menu)
⚠️ Validates bracket balance and warns about potential issues
🔒 Prevents overwriting existing snippet files
↩️ Full undo support via WorkspaceEdit

Usage:

Select the code you want to extract (in any template or snippet file)
Right-click and choose Kirby: Extract to Snippet
- Or use Command Palette: Kirby: Extract to Snippet
Enter snippet name (e.g., "header" or "partials/menu")
The selected code is moved to site/snippets/header.php
Original selection is replaced with <?php snippet('header') ?>

Example:

Before extraction:

<header class="site-header">
  <h1><?= $site->title() ?></h1>
  <nav><?= snippet('menu') ?></nav>
</header>

After extraction (with name "header"):

<?php snippet('header') ?>

New file site/snippets/header.php:

<?php
/**
 * @var \Kirby\Cms\Page $page
 * @var \Kirby\Cms\Site $site
 * @var \Kirby\Cms\App $kirby
 */
?>
<header class="site-header">
  <h1><?= $site->title() ?></h1>
  <nav><?= snippet('menu') ?></nav>
</header>

4. Tailwind CSS Integration

Automatic detection and configuration of Tailwind CSS IntelliSense for PHP templates.

Features:

🔍 Auto-detects Tailwind CSS in your project
⚡ One-click configuration for IntelliSense in PHP files
📦 Checks for Tailwind CSS IntelliSense extension
🔧 Updates workspace settings automatically
💾 Remembers your choice (doesn't prompt again)
📝 Manual configuration command available

How it works:

Extension detects tailwindcss in your package.json
Prompts: "Tailwind CSS detected. Enable IntelliSense for PHP templates?"
Click "Yes" to automatically configure workspace settings
Tailwind class completion now works in your PHP template files!

What gets configured:

{
  "tailwindCSS.includeLanguages": {
    "php": "html"
  }
}

Manual configuration:

Command: Kirby: Configure Tailwind IntelliSense
Reset prompt: Kirby: Reset Tailwind Integration Prompt

Requirements:

Tailwind CSS IntelliSense extension by Brad Cornes
tailwindcss in your project's dependencies or devDependencies

See available custom fields from your Blueprints directly in template files.

Features:

👁️ CodeLens shows Blueprint fields at the top of templates
🗺️ Automatic template-to-Blueprint matching
📊 Shows field names and optionally their types
✂️ Truncates long field lists intelligently
🔗 Click to open the corresponding Blueprint file
⚡ Caching for optimal performance
📝 Supports nested Blueprint structures (tabs, sections, columns)

Usage: Open any template file (e.g., site/templates/project.php), and you'll see a CodeLens at the top showing available fields from site/blueprints/pages/project.yml:

Blueprint Fields: title, description, image, date, tags ... (+3 more)

Click the CodeLens to open the Blueprint file and edit the field definitions.

Example:

Template: site/templates/article.php

CodeLens displays:

Blueprint Fields: title, author, date, text, tags, gallery

Now you know exactly which fields are available when writing:

<h1><?= $page->title() ?></h1>
<p>By <?= $page->author() ?> on <?= $page->date() ?></p>
<div><?= $page->text()->kirbytext() ?></div>

Seamlessly navigate between related files: Templates, Controllers, and Models.

Features:

🔗 CodeLens links for quick navigation
⚡ F12 / Ctrl+Click (Go-to-Definition) support
🔄 Bidirectional navigation (template ↔ controller ↔ model)
👁️ Peek Definition support
🎯 Multi-target navigation when multiple files exist
📝 Warning indicators for orphaned files
⚙️ Individually configurable navigation types

Usage:

From Templates:

See "Open Controller" and "Open Model" CodeLens links at the top
F12 on any part of the file to see all related files
Ctrl+Click to jump to controller or model

From Controllers:

See "Open Template" CodeLens link
F12 to jump back to the template

From Models:

See "Open Template" CodeLens link
Navigate back to the template instantly

Example:

site/templates/project.php shows:

Open Controller | Open Model

site/controllers/project.php shows:

Open Template

F12 (Go-to-Definition) from project.php template shows both:

site/controllers/project.php
site/models/project.php

7. Automatic Type-Hint Injection

Automatically inject PHPDoc type hints for Kirby's global variables ($page, $site, $kirby) in template and snippet files.

Features:

✨ Automatic injection when creating new template or snippet files
🎯 Manual injection via command: Kirby: Add Type Hints
⚙️ Configurable variable list
🔍 IntelliSense support with Intelephense

Usage:

Create a new PHP file in site/templates/ or site/snippets/ - type hints are added automatically
For existing files, use the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Kirby: Add Type Hints

8. Blueprint Schema Validation

JSON Schema validation and auto-completion for Kirby Blueprint YAML files.

Features:

✅ Real-time validation of Blueprint syntax
💡 Auto-completion for field types, sections, and options
📝 Inline documentation and hints
🎨 Syntax highlighting for Blueprint-specific keys

How it works:

Open any .yml file in site/blueprints/
Get instant validation and auto-completion powered by the official Kirby Blueprint schema

Schema Attribution: This extension bundles the Kirby Blueprint JSON Schema by bnomei, licensed under MIT.

9. Frontend Build Integration

Automatically manage Node.js build processes (Vite, Webpack, Tailwind CLI) directly from VS Code with integrated terminal management and status monitoring.

Features:

🔨 Auto-detect npm build scripts (dev, watch, build)
▶️ Start/stop/restart build watchers from Command Palette
📊 Real-time build status in the status bar
🖥️ Integrated terminal with clickable error links
🚀 Optional auto-start on workspace open
⚙️ Custom build command configuration
🎯 One-click access to build terminal

How it works:

Automatic Script Detection: The extension scans your package.json for common build scripts:

Dev/Watch mode: dev, watch, dev:css, watch:css
One-time build: build, build:css, compile

Commands:

Kirby: Start Build Watcher - Starts npm run dev or npm run watch
Kirby: Stop Build Watcher - Stops the active build process
Kirby: Restart Build Watcher - Restarts the build process
Kirby: Run Build Once - Runs npm run build (one-time)
Kirby: Show Build Terminal - Focuses the build terminal

Status Bar Indicator:

⚫ No build (gray) - No build process running
🔨 Building (yellow) - Build process active
✅ Build ready (green) - Build completed successfully
❌ Build error (red) - Build process failed

Click the status bar to show the build terminal.

Configuration Examples:

{
  // Enable build integration
  "kirby.enableBuildIntegration": true,

  // Custom build command (overrides auto-detection)
  "kirby.buildCommand": "npm run dev",

  // Auto-start build watcher on workspace open
  "kirby.buildAutoStart": false,

  // Which script to auto-start ("dev", "watch", or "build")
  "kirby.buildAutoStartScript": "dev",

  // Delay before auto-start (in milliseconds)
  "kirby.buildAutoStartDelay": 2000
}

Current Limitations:

Due to VS Code Terminal API constraints, the build integration has the following limitations:

Extension-Managed Builds Only: The extension can only monitor build processes it starts through its own commands (Kirby: Start Build Watcher, etc.). Builds started via VS Code's npm scripts panel or external terminals are not detected.
Watch Mode Rebuilds Not Detected: When using watch mode (e.g., npm run dev-server with webpack watch), the status bar shows "Build ready" after the initial build completes (5-second timeout). Subsequent rebuilds triggered by file changes are not detected - the status bar remains in "ready" state.
Timeout-Based Status: The "Build ready" state is determined by a 5-second timeout after starting the build terminal, not by parsing actual build output. The extension cannot read terminal output due to Terminal API limitations.
No Build Output Parsing: Build errors and warnings are only visible in the terminal itself. The extension cannot parse build tool output to detect specific errors or provide "jump to error" functionality.

Workarounds:

Use the extension's Kirby: Start Build Watcher command instead of the npm scripts panel for status bar integration
Check the build terminal directly for detailed output and error messages
The terminal output includes clickable file paths for most build tools (Vite, Webpack, etc.)

Supported Build Tools:

✅ Vite
✅ Webpack
✅ Tailwind CSS CLI
✅ PostCSS
✅ esbuild
✅ Any npm script-based build tool

Example package.json scripts:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "watch": "tailwindcss -i src/input.css -o dist/output.css --watch"
  }
}

Quickly navigate from snippet() function calls to their corresponding snippet files.

Features:

🔗 CodeLens links above snippet() calls
⚡ Go-to-Definition support (F12, Ctrl+Click)
👁️ Peek Definition support
🗂️ Support for nested snippets (e.g., snippet('partials/menu'))

Usage:

Click the "Open Snippet" link above any snippet() call
Or use F12 / Ctrl+Click (Cmd+Click on macOS) on the snippet name
Works in both templates and snippets

Requirements

VS Code: Version 1.60.0 or higher
Kirby CMS project: Extension detects and activates only in workspaces containing a site/ directory
YAML extension: The Red Hat YAML extension is required for Blueprint validation (automatically installed as dependency)

Extension Settings

This extension contributes the following settings:

Type Hints

kirby.autoInjectTypeHints: Enable/disable automatic type-hint injection on file creation (default: true)
kirby.typeHintVariables: Array of variable names to include in type-hint blocks (default: ["$page", "$site", "$kirby"])

Blueprint Validation

kirby.enableBlueprintValidation: Enable/disable Blueprint JSON Schema validation (default: true)
kirby.blueprintSchemaPath: Path to custom Blueprint JSON Schema file (leave empty to use bundled schema)

Blueprint Field CodeLens

kirby.showBlueprintFieldCodeLens: Show/hide CodeLens with Blueprint fields in templates (default: true)
kirby.showBlueprintFieldTypes: Show field types in Blueprint field CodeLens (default: false)
kirby.blueprintFieldDisplayLimit: Maximum number of fields to display before truncating (default: 5)

kirby.showSnippetCodeLens: Show/hide CodeLens links above snippet() calls (default: true)
kirby.showControllerNavigation: Show/hide navigation to controller files from templates (default: true)
kirby.showModelNavigation: Show/hide navigation to model files from templates (default: true)

Blueprint/Template Synchronization

kirby.enableBlueprintTemplateSync: Enable/disable automatic Blueprint/Template sync prompts (default: true)
kirby.syncPromptBehavior: How to handle sync prompts - "ask", "never", or "always" (default: "ask")
kirby.syncCreateController: Automatically create controller when creating template from Blueprint (default: false)
kirby.syncCreateModel: Automatically create model when creating template from Blueprint (default: false)
kirby.syncIgnoreFolders: Array of folder patterns to exclude from sync detection (default: [])

Frontend Build Integration

kirby.enableBuildIntegration: Enable/disable build integration features (default: true)
kirby.buildCommand: Custom build command to run (leave empty for auto-detection) (default: "")
kirby.buildAutoStart: Automatically start build watcher when opening workspace (default: false)
kirby.buildAutoStartScript: Which npm script to use for auto-start - "dev", "watch", or "build" (default: "dev")
kirby.buildAutoStartDelay: Delay in milliseconds before auto-starting build watcher (default: 2000)

Tailwind CSS

kirby.enableTailwindIntegration: Enable/disable automatic Tailwind CSS integration (default: true)

Installation

From VS Code Marketplace

The easiest way to install the extension:

Open VS Code
Go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
Search for "Kirby CMS Developer Toolkit"
Click "Install"

Or install directly from the command line:

code --install-extension MichaelvanLaar.vscode-kirby-toolkit

Marketplace page: https://marketplace.visualstudio.com/items?itemName=MichaelvanLaar.vscode-kirby-toolkit

From GitHub Releases

Go to the Releases page
Download the latest .vsix file
Open VS Code
Go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
Click the "..." menu at the top of the Extensions view
Select "Install from VSIX..."
Choose the downloaded .vsix file

Build from Source

If you want to build and install the extension yourself:

# Clone the repository
git clone https://github.com/MichaelvanLaar/vscode-kirby-toolkit.git
cd vscode-kirby-toolkit

# Install dependencies
npm install

# Build the VSIX file
npm install -g @vscode/vsce
vsce package

# This creates a .vsix file in the current directory
# Install it using the steps above (Extensions view → Install from VSIX)

Usage Tips

Page Type Scaffolding

Quick scaffolding:

1. Ctrl+Shift+P → "Kirby: New Page Type"
2. Enter name: "project"
3. Select files: Blueprint + Template + Controller
4. Done! All files created and ready to edit

Naming conventions:

Use lowercase with hyphens: blog-post, team-member
Use underscores: my_page
Model classes are auto-converted to PascalCase: blog-post → BlogPostPage

Snippet Extraction

Best practices:

Extract reusable components early (headers, footers, cards)
Use nested paths for organization: partials/navigation, components/card
The extension warns about unbalanced brackets - review before confirming
Extracted snippets automatically get type hints if enabled

Undo extraction: Just press Ctrl+Z (or Cmd+Z) - both the file creation and code replacement are undone together!

Viewing field types: Enable kirby.showBlueprintFieldTypes to see:

Blueprint Fields: title (text), description (textarea), image (files)

Adjusting field limit:

{
  "kirby.blueprintFieldDisplayLimit": 10
}

Shows up to 10 fields before truncating with "... (+N more)".

Keyboard shortcuts:

F12 - Go to Definition (jump to related file)
Alt+F12 - Peek Definition (preview without opening)
Ctrl+Click (Windows/Linux) or Cmd+Click (macOS) - Quick jump

Disabling specific navigation:

{
  "kirby.showControllerNavigation": false,  // Hide controller links
  "kirby.showModelNavigation": true         // Keep model links
}

Type Hints

Customizing Type-Hint Variables:

{
  "kirby.typeHintVariables": ["$page", "$site", "$kirby", "$pages"]
}

Disabling Automatic Injection:

If you prefer to add type hints manually:

{
  "kirby.autoInjectTypeHints": false
}

Then use the command Kirby: Add Type Hints when needed.

Blueprint Validation

The extension uses the Kirby 5 Blueprint schema by default. If you're working with custom Blueprint extensions or need a different schema version:

{
  "kirby.blueprintSchemaPath": "/path/to/custom/schema.json"
}

Disabling CodeLens:

If you find CodeLens links distracting but still want F12 navigation:

{
  "kirby.showSnippetCodeLens": false
}

This disables ALL CodeLens features (snippets, controllers, models, Blueprint fields).

Security & Quality

This extension has undergone comprehensive security review and testing:

✅ 232 automated tests covering all features (up from 36 in v0.2)
✅ Path traversal protection with multi-layer input sanitization
✅ Zero security vulnerabilities in dependencies
✅ Pre-commit testing via Husky hooks ensures every commit passes all tests
✅ Strict TypeScript compilation and ESLint validation
✅ Security-focused tests for file operations and path validation
✅ Atomic operations for file creation (undo support)
✅ Workspace settings only (never modifies user-global settings)

See SECURITY.md for detailed security information and vulnerability reporting.

Known Issues

Custom Kirby directory structures: Current version only supports the standard site/ directory structure
Regex-based PHP parsing: Snippet detection uses regex which may produce false positives in edge cases (e.g., snippet calls in comments)
Blueprint schema extends validation: When using the extends property in Blueprint fields (e.g., extends: fields/myfield), you may see a validation warning about a missing type property. This is a known limitation in the upstream JSON schema - according to Kirby documentation, the type property should be omitted when using extends, but the schema incorrectly requires it. Your blueprints will work correctly in Kirby despite this warning. See [bnomei/kirby-schema issue #38](https://github.com/bnomei/kirby-schema/issues/38) for tracking.
PHP AST limitations: Field navigation and code extraction rely on simple parsing, not full PHP AST analysis. Complex expressions may not be handled perfectly.

Roadmap

Planned features for future releases:

Bidirectional snippet navigation: Navigate from snippet files back to templates that use them
Enhanced field completion: IntelliSense for custom field names (e.g., $page->→)
Model method navigation: Jump from template method calls to model definitions
Blueprint field validation: Real-time validation of field usage in templates
Multi-workspace support: Better handling of multi-root workspaces

Contributing

Contributions are welcome! This project is open source.

Development Setup

Clone the repository
Run npm install
Open in VS Code
Press F5 to launch Extension Development Host
Test your changes

AI-Assisted Development (Optional)

This project uses Claude Code with Context7 MCP integration for enhanced AI-assisted development. The integration provides access to up-to-date documentation for VS Code Extension API and Kirby CMS.

Setup:

Copy .env.example to .env:
```
cp .env.example .env
```
Get your Context7 API key from context7.com
Add your API key to the .env file:
```
CONTEXT7_API_KEY=your-api-key-here
```
The MCP server is already configured in .mcp.json

Available Slash Commands:

The project includes custom slash commands for on-demand documentation retrieval:

/context7:vscode [topic] - Pull VS Code Extension API docs and samples
- Example: /context7:vscode FileSystemWatcher
- Example: /context7:vscode (general context)
/context7:kirby [topic] - Pull Kirby CMS documentation
- Example: /context7:kirby blueprints
- Example: /context7:kirby (general context)
/context7:full [topic] - Pull both VS Code and Kirby docs (comprehensive context)
- Example: /context7:full template validation
- Example: /context7:full (general context from both sources)

When to use Context7 commands:

✅ Working with unfamiliar or new APIs
✅ Troubleshooting complex issues
✅ Implementing features requiring deep understanding of both systems
✅ Verifying best practices or API changes
❌ Following existing patterns (usually not needed)
❌ Routine refactoring or similar features

Note: The .env file is ignored by git and will not be committed. Context7 integration is completely optional and not required for contributing to the project.

Building & Testing

npm run compile      # Compile TypeScript + copy schemas
npm run watch        # Watch mode for development
npm run lint         # Run ESLint validation
npm run test         # Run all 232 tests (compile + lint + test suite)

Quality Assurance:

All commits are automatically tested via pre-commit hooks
Tests must pass before code can be committed
232 tests covering security, parsing, scaffolding, refactoring, navigation, integration, and build automation
Zero tolerance for security vulnerabilities

Packaging

npm install -g @vscode/vsce
vsce package

License

This extension is licensed under the MIT License.

Bundled Dependencies

Kirby Blueprint JSON Schema: MIT License © bnomei - The complete license is bundled with this extension in src/schemas/LICENSE. Original repository: bnomei/kirby-schema

Acknowledgments

Kirby CMS - The amazing file-based CMS
bnomei - For the Kirby Blueprint JSON Schema
The Kirby community for inspiration and feedback

Support

Issues: Report bugs or request features
Security: Report vulnerabilities
Kirby Forum: Join the discussion at forum.getkirby.com

Enjoy developing with Kirby CMS! 🚀

Kirby CMS Developer Toolkit

Michael van Laar

Kirby CMS Developer Toolkit

Features

1. Page Type Scaffolding

2. Blueprint/Template Synchronization

3. Extract to Snippet

4. Tailwind CSS Integration

5. Blueprint Field Navigation

6. Extended File Navigation

7. Automatic Type-Hint Injection

8. Blueprint Schema Validation

9. Frontend Build Integration

10. Snippet Navigation

Requirements

Extension Settings

Type Hints

Blueprint Validation

Blueprint Field CodeLens

Navigation

Blueprint/Template Synchronization

Frontend Build Integration

Tailwind CSS

Installation

From VS Code Marketplace

From GitHub Releases

Build from Source

Usage Tips

Page Type Scaffolding

Snippet Extraction

Blueprint Field Navigation

File Navigation

Type Hints

Blueprint Validation

Snippet Navigation

Security & Quality

Known Issues

Roadmap

Contributing

Development Setup

AI-Assisted Development (Optional)

Building & Testing

Packaging

License

Bundled Dependencies

Acknowledgments

Support