{"id":32791497,"url":"https://github.com/michaelvanlaar/vscode-kirby-toolkit","last_synced_at":"2026-05-16T09:34:50.907Z","repository":{"id":320695504,"uuid":"1082831627","full_name":"MichaelvanLaar/vscode-kirby-toolkit","owner":"MichaelvanLaar","description":"VS Code extension for Kirby CMS development","archived":false,"fork":false,"pushed_at":"2025-11-02T00:40:26.000Z","size":473,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-02T02:31:26.035Z","etag":null,"topics":["kirby","kirby-cms","vs-code","vs-code-extenstion","vscode","vscode-extension","webdev","webdevelopment"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MichaelvanLaar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-24T20:53:57.000Z","updated_at":"2025-11-02T00:40:26.000Z","dependencies_parsed_at":"2025-10-25T10:26:26.417Z","dependency_job_id":"4a31865a-75a5-432c-ba59-f8b9deba3d6c","html_url":"https://github.com/MichaelvanLaar/vscode-kirby-toolkit","commit_stats":null,"previous_names":["michaelvanlaar/vscode-kirby-toolkit"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/MichaelvanLaar/vscode-kirby-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelvanLaar%2Fvscode-kirby-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelvanLaar%2Fvscode-kirby-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelvanLaar%2Fvscode-kirby-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelvanLaar%2Fvscode-kirby-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MichaelvanLaar","download_url":"https://codeload.github.com/MichaelvanLaar/vscode-kirby-toolkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelvanLaar%2Fvscode-kirby-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282823603,"owners_count":26733133,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-05T02:00:05.946Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kirby","kirby-cms","vs-code","vs-code-extenstion","vscode","vscode-extension","webdev","webdevelopment"],"created_at":"2025-11-05T13:01:00.228Z","updated_at":"2026-05-16T09:34:50.898Z","avatar_url":"https://github.com/MichaelvanLaar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kirby CMS Developer Toolkit\n\nA 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.\n\n\u003e **Note:** This is an unofficial third-party extension and is not affiliated with or endorsed by Kirby CMS.\n\n## Features\n\n### 1. Page Type Scaffolding\n\nQuickly generate complete page types with all necessary files through an interactive wizard.\n\n**Features:**\n- 🚀 Interactive command palette wizard\n- 📝 Generates Blueprint YAML with sensible defaults\n- 🎨 Creates HTML5 template boilerplate\n- ⚙️ Optional Controller and Model file generation\n- 🔒 Built-in security validation for file names\n- ✨ Automatic type-hint injection in templates\n- 📂 Creates necessary directories automatically\n\n**Usage:**\n1. Open Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)\n2. Run `Kirby: New Page Type`\n3. Enter the page type name (e.g., \"project\", \"article\")\n4. Select which files to generate:\n   - Blueprint (Required) - `site/blueprints/pages/project.yml`\n   - Template (Required) - `site/templates/project.php`\n   - Controller (Optional) - `site/controllers/project.php`\n   - Model (Optional) - `site/models/project.php`\n5. Files are created with sensible defaults and opened automatically\n\n**Example Output:**\n\nBlueprint (`site/blueprints/pages/project.yml`):\n```yaml\ntitle: Project\n\nfields:\n  title:\n    type: text\n    label: Title\n  text:\n    type: textarea\n    label: Text\n```\n\nTemplate (`site/templates/project.php`):\n```php\n\u003c?php\n/**\n * @var \\Kirby\\Cms\\Page $page\n * @var \\Kirby\\Cms\\Site $site\n * @var \\Kirby\\Cms\\App $kirby\n */\n?\u003e\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n  \u003cmeta charset=\"UTF-8\"\u003e\n  \u003ctitle\u003e\u003c?= $page-\u003etitle() ?\u003e\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  \u003ch1\u003e\u003c?= $page-\u003etitle() ?\u003e\u003c/h1\u003e\n  \u003cdiv\u003e\u003c?= $page-\u003etext()-\u003ekirbytext() ?\u003e\u003c/div\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nModel (`site/models/project.php`):\n```php\n\u003c?php\n\nuse Kirby\\Cms\\Page;\n\nclass ProjectPage extends Page\n{\n  // Add custom page methods here\n}\n```\n\n### 2. Blueprint/Template Synchronization\n\nAutomatically detect missing counterpart files when you create a Blueprint or Template (including blocks and fields), and offer to create them with one click.\n\n**Features:**\n- 🔄 Monitors Blueprint and Template file creation in real-time\n- 📝 Prompts to create missing counterparts automatically\n- ⚙️ Optional Controller and Model file creation (for page templates)\n- 🧩 **NEW: Block snippet synchronization** (enabled by default)\n- 📋 **NEW: Field snippet synchronization** (opt-in)\n- 🎯 Handles nested Blueprint structures (e.g., `blog/post.yml` → `blog.post.php`)\n- 🔕 \"Don't ask again\" option with workspace-specific memory\n- ⚡ Smart debouncing to avoid notification spam during bulk operations\n- 🛠️ Three behavior modes: Ask (default), Never, Always\n- 📁 Supports both flat (dot notation) and nested directory structures for blocks\n\n**How it works:**\n\n**Scenario 1: Creating a Blueprint**\n1. Create a new Blueprint file: `site/blueprints/pages/article.yml`\n2. Extension detects no matching template exists\n3. Notification appears: \"📄 Blueprint 'article.yml' created without a template. Create 'article.php'?\"\n4. Choose:\n   - **Create Template** - Creates basic template with HTML boilerplate\n   - **Create Template + Controller + Model** - Creates all three files\n   - **Don't ask again** - Remembers choice for this workspace\n   - **Dismiss** - Skip this time only\n\n**Scenario 2: Creating a Template**\n1. Create a new template file: `site/templates/project.php`\n2. Extension detects no matching Blueprint exists\n3. Notification appears: \"📄 Template 'project.php' created without a Blueprint. Create Blueprint?\"\n4. Choose:\n   - **Create Blueprint** - Creates Blueprint with sensible field defaults\n   - **Don't ask again** - Remembers choice for this workspace\n   - **Dismiss** - Skip this time only\n\n**Nested Blueprint Support:**\n- `site/blueprints/pages/blog/post.yml` → `site/templates/blog.post.php`\n- `site/templates/section.article.php` → `site/blueprints/pages/section/article.yml`\n\n**Configuration Options:**\n```json\n{\n  \"kirby.enableBlueprintTemplateSync\": true,       // Master toggle\n  \"kirby.syncPromptBehavior\": \"ask\",               // \"ask\" | \"never\" | \"always\"\n  \"kirby.syncCreateController\": false,             // Auto-create controller by default\n  \"kirby.syncCreateModel\": false,                  // Auto-create model by default\n  \"kirby.syncBlockSnippets\": true,                 // Enable block synchronization\n  \"kirby.syncFieldSnippets\": false,                // Enable field synchronization (opt-in)\n  \"kirby.syncBlockNestingStrategy\": \"auto\",        // \"auto\" | \"flat\" | \"nested\"\n  \"kirby.syncIgnoreFolders\": [\"test/\", \"archive/\"] // Exclude patterns\n}\n```\n\n**Block Synchronization:**\n- Automatically creates matching snippets for block Blueprints in `site/blueprints/blocks/`\n- Supports both flat (`gallery.image.php`) and nested (`gallery/image.php`) directory structures\n- Auto-detects nesting strategy from existing files or uses configured preference\n- Bidirectional: Create Blueprint from snippet or snippet from Blueprint\n\n**Field Synchronization:**\n- Opt-in feature for developers who create custom field snippets\n- Blueprint-first workflow: Only prompts when creating field Blueprints\n- Creates snippets in `site/snippets/fields/` directory\n\n**Behavior Modes:**\n- **\"ask\"** (default): Show notification with action buttons\n- **\"never\"**: Completely disable sync prompts\n- **\"always\"**: Automatically create missing files without prompting\n\n**Reset Dismissed Prompts:**\nRun `Kirby: Reset Blueprint/Template Sync Prompts` to clear all \"Don't ask again\" choices.\n\n**Use Cases:**\n- **Quick prototyping**: Create Blueprint first, get Template automatically\n- **Consistency enforcement**: Never forget to create matching files\n- **Team workflows**: Standardize file creation across team members\n- **Bulk operations**: Smart debouncing prevents notification spam during git operations\n\n### 3. Extract to Snippet\n\nRefactor selected code into reusable snippets with automatic replacement.\n\n**Features:**\n- ✂️ Extract any selected code to a new snippet file\n- 🔄 Automatically replaces selection with `snippet()` call\n- 🎯 Smart PHP context detection (adds tags only when needed)\n- 📐 Preserves indentation perfectly\n- 🗂️ Supports nested snippet paths (e.g., `partials/menu`)\n- ⚠️ Validates bracket balance and warns about potential issues\n- 🔒 Prevents overwriting existing snippet files\n- ↩️ Full undo support via WorkspaceEdit\n\n**Usage:**\n1. Select the code you want to extract (in any template or snippet file)\n2. Right-click and choose `Kirby: Extract to Snippet`\n   - Or use Command Palette: `Kirby: Extract to Snippet`\n3. Enter snippet name (e.g., \"header\" or \"partials/menu\")\n4. The selected code is moved to `site/snippets/header.php`\n5. Original selection is replaced with `\u003c?php snippet('header') ?\u003e`\n\n**Example:**\n\nBefore extraction:\n```php\n\u003cheader class=\"site-header\"\u003e\n  \u003ch1\u003e\u003c?= $site-\u003etitle() ?\u003e\u003c/h1\u003e\n  \u003cnav\u003e\u003c?= snippet('menu') ?\u003e\u003c/nav\u003e\n\u003c/header\u003e\n```\n\nAfter extraction (with name \"header\"):\n```php\n\u003c?php snippet('header') ?\u003e\n```\n\nNew file `site/snippets/header.php`:\n```php\n\u003c?php\n/**\n * @var \\Kirby\\Cms\\Page $page\n * @var \\Kirby\\Cms\\Site $site\n * @var \\Kirby\\Cms\\App $kirby\n */\n?\u003e\n\u003cheader class=\"site-header\"\u003e\n  \u003ch1\u003e\u003c?= $site-\u003etitle() ?\u003e\u003c/h1\u003e\n  \u003cnav\u003e\u003c?= snippet('menu') ?\u003e\u003c/nav\u003e\n\u003c/header\u003e\n```\n\n### 4. Tailwind CSS Integration\n\nAutomatic detection and configuration of Tailwind CSS IntelliSense for PHP templates.\n\n**Features:**\n- 🔍 Auto-detects Tailwind CSS in your project\n- ⚡ One-click configuration for IntelliSense in PHP files\n- 📦 Checks for Tailwind CSS IntelliSense extension\n- 🔧 Updates workspace settings automatically\n- 💾 Remembers your choice (doesn't prompt again)\n- 📝 Manual configuration command available\n\n**How it works:**\n1. Extension detects `tailwindcss` in your `package.json`\n2. Prompts: \"Tailwind CSS detected. Enable IntelliSense for PHP templates?\"\n3. Click \"Yes\" to automatically configure workspace settings\n4. Tailwind class completion now works in your PHP template files!\n\n**What gets configured:**\n```json\n{\n  \"tailwindCSS.includeLanguages\": {\n    \"php\": \"html\"\n  }\n}\n```\n\n**Manual configuration:**\n- Command: `Kirby: Configure Tailwind IntelliSense`\n- Reset prompt: `Kirby: Reset Tailwind Integration Prompt`\n\n**Requirements:**\n- [Tailwind CSS IntelliSense extension](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) by Brad Cornes\n- `tailwindcss` in your project's dependencies or devDependencies\n\n### 5. Blueprint Field Navigation\n\nSee available custom fields from your Blueprints directly in template files.\n\n**Features:**\n- 👁️ CodeLens shows Blueprint fields at the top of templates\n- 🗺️ Automatic template-to-Blueprint matching\n- 📊 Shows field names and optionally their types\n- ✂️ Truncates long field lists intelligently\n- 🔗 Click to open the corresponding Blueprint file\n- ⚡ Caching for optimal performance\n- 📝 Supports nested Blueprint structures (tabs, sections, columns)\n\n**Usage:**\nOpen 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`:\n\n```\nBlueprint Fields: title, description, image, date, tags ... (+3 more)\n```\n\nClick the CodeLens to open the Blueprint file and edit the field definitions.\n\n**Example:**\n\nTemplate: `site/templates/article.php`\n\nCodeLens displays:\n```\nBlueprint Fields: title, author, date, text, tags, gallery\n```\n\nNow you know exactly which fields are available when writing:\n```php\n\u003ch1\u003e\u003c?= $page-\u003etitle() ?\u003e\u003c/h1\u003e\n\u003cp\u003eBy \u003c?= $page-\u003eauthor() ?\u003e on \u003c?= $page-\u003edate() ?\u003e\u003c/p\u003e\n\u003cdiv\u003e\u003c?= $page-\u003etext()-\u003ekirbytext() ?\u003e\u003c/div\u003e\n```\n\n### 6. Extended File Navigation\n\nSeamlessly navigate between related files: Templates, Controllers, and Models.\n\n**Features:**\n- 🔗 CodeLens links for quick navigation\n- ⚡ F12 / Ctrl+Click (Go-to-Definition) support\n- 🔄 Bidirectional navigation (template ↔ controller ↔ model)\n- 👁️ Peek Definition support\n- 🎯 Multi-target navigation when multiple files exist\n- 📝 Warning indicators for orphaned files\n- ⚙️ Individually configurable navigation types\n\n**Usage:**\n\n**From Templates:**\n- See \"Open Controller\" and \"Open Model\" CodeLens links at the top\n- F12 on any part of the file to see all related files\n- Ctrl+Click to jump to controller or model\n\n**From Controllers:**\n- See \"Open Template\" CodeLens link\n- F12 to jump back to the template\n\n**From Models:**\n- See \"Open Template\" CodeLens link\n- Navigate back to the template instantly\n\n**Example:**\n\n`site/templates/project.php` shows:\n```\nOpen Controller | Open Model\n```\n\n`site/controllers/project.php` shows:\n```\nOpen Template\n```\n\nF12 (Go-to-Definition) from `project.php` template shows both:\n- `site/controllers/project.php`\n- `site/models/project.php`\n\n### 7. Automatic Type-Hint Injection\n\nAutomatically inject PHPDoc type hints for Kirby's global variables (`$page`, `$site`, `$kirby`) in template and snippet files.\n\n**Features:**\n- ✨ Automatic injection when creating new template or snippet files\n- 🎯 Manual injection via command: `Kirby: Add Type Hints`\n- ⚙️ Configurable variable list\n- 🔍 IntelliSense support with Intelephense\n\n**Usage:**\n- Create a new PHP file in `site/templates/` or `site/snippets/` - type hints are added automatically\n- For existing files, use the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run `Kirby: Add Type Hints`\n\n### 8. Kirby API IntelliSense\n\nIntelligent autocompletion and inline documentation for Kirby CMS API classes and methods, powered by PHP stubs and the Intelephense language server.\n\n**Features:**\n- 💡 Smart autocompletion for Kirby core classes (`Page`, `Site`, `File`, `User`, `Kirby`, `Field`)\n- 📖 Inline documentation with hover tooltips\n- 🔗 Links to official Kirby documentation\n- ⛓️ Method chaining support with return type inference\n- 🎯 Signature help for method parameters\n- 🔧 Automatic stub installation and configuration\n- 🎛️ Optional custom stub paths for advanced use cases\n\n**How it works:**\n1. Extension automatically detects Intelephense PHP language server\n2. Copies Kirby API stub files to `.vscode/kirby-stubs/` in your workspace\n3. Configures Intelephense to index the stubs\n4. You get instant autocompletion and documentation for all Kirby API methods!\n\n**Usage:**\nSimply type `$page-\u003e` in any PHP file and see all available Page methods with descriptions:\n- `$page-\u003etitle()` - Returns the page's title field\n- `$page-\u003echildren()` - Returns a collection of child pages\n- `$page-\u003eurl()` - Returns the page's URL\n- And many more...\n\n**Supported Classes:**\n- **Page**: `title()`, `children()`, `parent()`, `url()`, `files()`, `images()`, etc.\n- **Site**: `children()`, `find()`, `pages()`, `users()`, `homePage()`, etc.\n- **File**: `url()`, `filename()`, `type()`, `size()`, `resize()`, `crop()`, etc.\n- **User**: `email()`, `name()`, `role()`, `isAdmin()`, `avatar()`, etc.\n- **Kirby/App**: `site()`, `users()`, `option()`, `roots()`, `urls()`, etc.\n- **Field**: `value()`, `isEmpty()`, `html()`, `markdown()`, `kirbytext()`, etc.\n- **Collections**: `Pages`, `Files`, `Users` with methods like `find()`, `first()`, `sortBy()`, etc.\n\n**Example:**\n```php\n\u003c?php\n// Type $page-\u003e and see all available methods with descriptions\n$page-\u003etitle()-\u003evalue()  // ← IntelliSense shows Field methods\n$page-\u003echildren()-\u003efirst()-\u003eurl()  // ← Chaining works perfectly\n$site-\u003efind('blog')-\u003echildren()  // ← All Kirby classes supported\n```\n\n**Requirements:**\n- [Intelephense](https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client) extension (free version works)\n- Recommended: Disable or configure other PHP extensions to avoid conflicts\n\n**Troubleshooting:**\nIf stubs aren't appearing in IntelliSense:\n1. Check that Intelephense extension is installed and enabled\n2. Verify `.vscode/kirby-stubs/` directory exists in your workspace\n3. Check workspace `settings.json` for `intelephense.stubs` configuration\n4. Run `Kirby: Reinstall API Stubs` command to force refresh\n5. Restart VS Code to trigger Intelephense reindex\n\n**Commands:**\n- `Kirby: Remove API Stubs` - Clean up stub files\n- `Kirby: Reinstall API Stubs` - Force reinstall/refresh stubs\n\n**Configuration:**\n```json\n{\n  \"kirby.enableApiIntelliSense\": true,     // Master toggle\n  \"kirby.kirbyVersion\": \"4.0\",             // API version (currently only 4.0)\n  \"kirby.customStubsPath\": \"\"              // Custom stub directory (optional)\n}\n```\n\n**What's Included:**\nBased on **Kirby 4.0 API** with comprehensive method signatures and PHPDoc annotations extracted from official documentation.\n\n### 9. Blueprint Schema Validation\n\nJSON Schema validation and auto-completion for Kirby Blueprint YAML files.\n\n**Features:**\n- ✅ Real-time validation of Blueprint syntax\n- 💡 Auto-completion for field types, sections, and options\n- 📝 Inline documentation and hints\n- 🎨 Syntax highlighting for Blueprint-specific keys\n\n**How it works:**\n- Open any `.yml` file in `site/blueprints/`\n- Get instant validation and auto-completion powered by the official Kirby Blueprint schema\n\n**Schema Attribution:**\nThis extension bundles the [Kirby Blueprint JSON Schema](https://github.com/bnomei/kirby-schema) by [bnomei](https://github.com/bnomei), licensed under MIT.\n\n### 10. Frontend Build Integration\n\nAutomatically manage Node.js build processes (Vite, Webpack, Tailwind CLI) directly from VS Code with integrated terminal management and status monitoring.\n\n**Features:**\n- 🔨 Auto-detect npm build scripts (`dev`, `watch`, `build`)\n- ▶️ Start/stop/restart build watchers from Command Palette\n- 📊 Real-time build status in the status bar\n- 🖥️ Integrated terminal with clickable error links\n- 🚀 Optional auto-start on workspace open\n- ⚙️ Custom build command configuration\n- 🎯 One-click access to build terminal\n\n**How it works:**\n\n**Automatic Script Detection:**\nThe extension scans your `package.json` for common build scripts:\n- **Dev/Watch mode**: `dev`, `watch`, `dev:css`, `watch:css`\n- **One-time build**: `build`, `build:css`, `compile`\n\n**Commands:**\n- `Kirby: Start Build Watcher` - Starts `npm run dev` or `npm run watch`\n- `Kirby: Stop Build Watcher` - Stops the active build process\n- `Kirby: Restart Build Watcher` - Restarts the build process\n- `Kirby: Run Build Once` - Runs `npm run build` (one-time)\n- `Kirby: Show Build Terminal` - Focuses the build terminal\n\n**Status Bar Indicator:**\n- ⚫ **No build** (gray) - No build process running\n- 🔨 **Building** (yellow) - Build process active\n- ✅ **Build ready** (green) - Build completed successfully\n- ❌ **Build error** (red) - Build process failed\n\nClick the status bar to show the build terminal.\n\n**Configuration Examples:**\n\n```json\n{\n  // Enable build integration\n  \"kirby.enableBuildIntegration\": true,\n\n  // Custom build command (overrides auto-detection)\n  \"kirby.buildCommand\": \"npm run dev\",\n\n  // Auto-start build watcher on workspace open\n  \"kirby.buildAutoStart\": false,\n\n  // Which script to auto-start (\"dev\", \"watch\", or \"build\")\n  \"kirby.buildAutoStartScript\": \"dev\",\n\n  // Delay before auto-start (in milliseconds)\n  \"kirby.buildAutoStartDelay\": 2000\n}\n```\n\n**Current Limitations:**\n\nDue to VS Code Terminal API constraints, the build integration has the following limitations:\n\n1. **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.\n\n2. **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.\n\n3. **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.\n\n4. **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.\n\n**Workarounds:**\n- Use the extension's `Kirby: Start Build Watcher` command instead of the npm scripts panel for status bar integration\n- Check the build terminal directly for detailed output and error messages\n- The terminal output includes clickable file paths for most build tools (Vite, Webpack, etc.)\n\n**Supported Build Tools:**\n- ✅ Vite\n- ✅ Webpack\n- ✅ Tailwind CSS CLI\n- ✅ PostCSS\n- ✅ esbuild\n- ✅ Any npm script-based build tool\n\n**Example package.json scripts:**\n```json\n{\n  \"scripts\": {\n    \"dev\": \"vite\",\n    \"build\": \"vite build\",\n    \"watch\": \"tailwindcss -i src/input.css -o dist/output.css --watch\"\n  }\n}\n```\n\n### 11. Snippet Navigation \u0026 Controller Support\n\nQuickly navigate from `snippet()` function calls to their corresponding snippet files, and seamlessly work with snippet controllers when using the [Kirby Snippet Controller plugin](https://github.com/lukaskleinschmidt/kirby-snippet-controller).\n\n**Features:**\n- 🔗 CodeLens links above `snippet()` calls\n- ⚡ Go-to-Definition support (F12, Ctrl+Click)\n- 👁️ Peek Definition support\n- 🗂️ Support for nested snippets (e.g., `snippet('partials/menu')`)\n- 🎮 **NEW: Snippet Controller support** - Navigate between snippets and their controllers\n- 🔍 **NEW: Automatic plugin detection** - Detects Kirby Snippet Controller plugin via composer.json or site/plugins/\n- 📝 **NEW: Type-hint injection** - Automatic type-hints for snippet controller files\n- 🧭 **NEW: Bidirectional navigation** - Navigate from snippets to controllers and vice versa\n\n**Usage:**\n- Click the \"Open Snippet\" or \"Open Controller\" link above any `snippet()` call\n- Or use F12 / Ctrl+Click (Cmd+Click on macOS) on the snippet name to see both targets\n- Navigate between snippet and controller files using CodeLens at the top of each file\n- Works in templates, snippets, and snippet controllers\n\n**Snippet Controller Support:**\n\nWhen the [Kirby Snippet Controller plugin](https://github.com/lukaskleinschmidt/kirby-snippet-controller) is detected in your project:\n- CodeLens shows both \"Open Snippet\" and \"Open Controller\" links above `snippet()` calls\n- F12 (Go-to-Definition) shows both snippet and controller as navigation targets\n- Snippet files display \"Open Snippet Controller\" CodeLens when a controller exists\n- Controller files display \"Open Snippet\" CodeLens to navigate back\n- Automatic type-hint injection when creating new snippet controller files\n- Supports nested snippets (e.g., `partials/menu.controller.php`)\n\n## Requirements\n\n- **VS Code**: Version 1.60.0 or higher\n- **Kirby CMS project**: Extension detects and activates only in workspaces containing a `site/` directory\n- **YAML extension**: The [Red Hat YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) is required for Blueprint validation (automatically installed as dependency)\n\n## Extension Settings\n\nThis extension contributes the following settings:\n\n### Type Hints\n* `kirby.autoInjectTypeHints`: Enable/disable automatic type-hint injection on file creation (default: `true`)\n* `kirby.typeHintVariables`: Array of variable names to include in type-hint blocks (default: `[\"$page\", \"$site\", \"$kirby\"]`)\n\n### Blueprint Validation\n* `kirby.enableBlueprintValidation`: Enable/disable Blueprint JSON Schema validation (default: `true`)\n* `kirby.blueprintSchemaPath`: Path to custom Blueprint JSON Schema file (leave empty to use bundled schema)\n\n### Blueprint Field CodeLens\n* `kirby.showBlueprintFieldCodeLens`: Show/hide CodeLens with Blueprint fields in templates (default: `true`)\n* `kirby.showBlueprintFieldTypes`: Show field types in Blueprint field CodeLens (default: `false`)\n* `kirby.blueprintFieldDisplayLimit`: Maximum number of fields to display before truncating (default: `5`)\n\n### Navigation\n* `kirby.showSnippetCodeLens`: Show/hide CodeLens links above snippet() calls (default: `true`)\n* `kirby.showControllerNavigation`: Show/hide navigation to controller files from templates (default: `true`)\n* `kirby.showModelNavigation`: Show/hide navigation to model files from templates (default: `true`)\n* `kirby.enableSnippetControllers`: Enable/disable snippet controller support (navigation, type-hints, CodeLens) (default: `true`)\n\n### Blueprint/Template Synchronization\n* `kirby.enableBlueprintTemplateSync`: Enable/disable automatic Blueprint/Template sync prompts (default: `true`)\n* `kirby.syncPromptBehavior`: How to handle sync prompts - `\"ask\"`, `\"never\"`, or `\"always\"` (default: `\"ask\"`)\n* `kirby.syncCreateController`: Automatically create controller when creating template from Blueprint (default: `false`)\n* `kirby.syncCreateModel`: Automatically create model when creating template from Blueprint (default: `false`)\n* `kirby.syncIgnoreFolders`: Array of folder patterns to exclude from sync detection (default: `[]`)\n\n### Frontend Build Integration\n* `kirby.enableBuildIntegration`: Enable/disable build integration features (default: `true`)\n* `kirby.buildCommand`: Custom build command to run (leave empty for auto-detection) (default: `\"\"`)\n* `kirby.buildAutoStart`: Automatically start build watcher when opening workspace (default: `false`)\n* `kirby.buildAutoStartScript`: Which npm script to use for auto-start - `\"dev\"`, `\"watch\"`, or `\"build\"` (default: `\"dev\"`)\n* `kirby.buildAutoStartDelay`: Delay in milliseconds before auto-starting build watcher (default: `2000`)\n\n### Tailwind CSS\n* `kirby.enableTailwindIntegration`: Enable/disable automatic Tailwind CSS integration (default: `true`)\n\n### API IntelliSense\n* `kirby.enableApiIntelliSense`: Enable/disable Kirby API IntelliSense via Intelephense (default: `true`)\n* `kirby.kirbyVersion`: Kirby CMS version for API stubs (default: `\"4.0\"`)\n* `kirby.customStubsPath`: Custom path to Kirby API stub files (default: `\"\"`)\n\n## Installation\n\n### From VS Code Marketplace\n\nThe easiest way to install the extension:\n\n1. Open VS Code\n2. Go to Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`)\n3. Search for \"Kirby CMS Developer Toolkit\"\n4. Click \"Install\"\n\nOr install directly from the command line:\n```bash\ncode --install-extension MichaelvanLaar.vscode-kirby-toolkit\n```\n\nMarketplace page: https://marketplace.visualstudio.com/items?itemName=MichaelvanLaar.vscode-kirby-toolkit\n\n### From GitHub Releases\n\n1. Go to the [Releases page](https://github.com/MichaelvanLaar/vscode-kirby-toolkit/releases)\n2. Download the latest `.vsix` file\n3. Open VS Code\n4. Go to Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`)\n5. Click the \"...\" menu at the top of the Extensions view\n6. Select \"Install from VSIX...\"\n7. Choose the downloaded `.vsix` file\n\n### Build from Source\n\nIf you want to build and install the extension yourself:\n\n```bash\n# Clone the repository\ngit clone https://github.com/MichaelvanLaar/vscode-kirby-toolkit.git\ncd vscode-kirby-toolkit\n\n# Install dependencies\nnpm install\n\n# Build the VSIX file\nnpm install -g @vscode/vsce\nvsce package\n\n# This creates a .vsix file in the current directory\n# Install it using the steps above (Extensions view → Install from VSIX)\n```\n\n## Usage Tips\n\n### Page Type Scaffolding\n\n**Quick scaffolding:**\n```\n1. Ctrl+Shift+P → \"Kirby: New Page Type\"\n2. Enter name: \"project\"\n3. Select files: Blueprint + Template + Controller\n4. Done! All files created and ready to edit\n```\n\n**Naming conventions:**\n- Use lowercase with hyphens: `blog-post`, `team-member`\n- Use underscores: `my_page`\n- Model classes are auto-converted to PascalCase: `blog-post` → `BlogPostPage`\n\n### Snippet Extraction\n\n**Best practices:**\n- Extract reusable components early (headers, footers, cards)\n- Use nested paths for organization: `partials/navigation`, `components/card`\n- The extension warns about unbalanced brackets - review before confirming\n- Extracted snippets automatically get type hints if enabled\n\n**Undo extraction:**\nJust press `Ctrl+Z` (or `Cmd+Z`) - both the file creation and code replacement are undone together!\n\n### Blueprint Field Navigation\n\n**Viewing field types:**\nEnable `kirby.showBlueprintFieldTypes` to see:\n```\nBlueprint Fields: title (text), description (textarea), image (files)\n```\n\n**Adjusting field limit:**\n```json\n{\n  \"kirby.blueprintFieldDisplayLimit\": 10\n}\n```\n\nShows up to 10 fields before truncating with \"... (+N more)\".\n\n### File Navigation\n\n**Keyboard shortcuts:**\n- `F12` - Go to Definition (jump to related file)\n- `Alt+F12` - Peek Definition (preview without opening)\n- `Ctrl+Click` (Windows/Linux) or `Cmd+Click` (macOS) - Quick jump\n\n**Disabling specific navigation:**\n```json\n{\n  \"kirby.showControllerNavigation\": false,  // Hide controller links\n  \"kirby.showModelNavigation\": true         // Keep model links\n}\n```\n\n### Type Hints\n\n**Customizing Type-Hint Variables:**\n\n```json\n{\n  \"kirby.typeHintVariables\": [\"$page\", \"$site\", \"$kirby\", \"$pages\"]\n}\n```\n\n**Disabling Automatic Injection:**\n\nIf you prefer to add type hints manually:\n\n```json\n{\n  \"kirby.autoInjectTypeHints\": false\n}\n```\n\nThen use the command `Kirby: Add Type Hints` when needed.\n\n### Blueprint Validation\n\nThe extension uses the Kirby 5 Blueprint schema by default. If you're working with custom Blueprint extensions or need a different schema version:\n\n```json\n{\n  \"kirby.blueprintSchemaPath\": \"/path/to/custom/schema.json\"\n}\n```\n\n### Snippet Navigation\n\n**Disabling CodeLens:**\n\nIf you find CodeLens links distracting but still want F12 navigation:\n\n```json\n{\n  \"kirby.showSnippetCodeLens\": false\n}\n```\n\nThis disables ALL CodeLens features (snippets, controllers, models, Blueprint fields).\n\n## Security \u0026 Quality\n\nThis extension has undergone comprehensive security review and testing:\n\n- ✅ **232 automated tests** covering all features (up from 36 in v0.2)\n- ✅ **Path traversal protection** with multi-layer input sanitization\n- ✅ **Zero security vulnerabilities** in dependencies\n- ✅ **Pre-commit testing** via Husky hooks ensures every commit passes all tests\n- ✅ **Strict TypeScript** compilation and ESLint validation\n- ✅ **Security-focused tests** for file operations and path validation\n- ✅ **Atomic operations** for file creation (undo support)\n- ✅ **Workspace settings only** (never modifies user-global settings)\n\nSee [SECURITY.md](SECURITY.md) for detailed security information and vulnerability reporting.\n\n## Known Issues\n\n- **Custom Kirby directory structures**: Current version only supports the standard `site/` directory structure\n- **Regex-based PHP parsing**: Snippet detection uses regex which may produce false positives in edge cases (e.g., snippet calls in comments)\n- **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.\n- **PHP AST limitations**: Field navigation and code extraction rely on simple parsing, not full PHP AST analysis. Complex expressions may not be handled perfectly.\n\n## Roadmap\n\nPlanned features for future releases:\n\n- **Bidirectional snippet navigation**: Navigate from snippet files back to templates that use them\n- **Enhanced field completion**: IntelliSense for custom field names (e.g., `$page-\u003e→`)\n- **Model method navigation**: Jump from template method calls to model definitions\n- **Blueprint field validation**: Real-time validation of field usage in templates\n- **Multi-workspace support**: Better handling of multi-root workspaces\n\n## Contributing\n\nContributions are welcome! This project is open source.\n\n### Development Setup\n\n1. Clone the repository\n2. Run `npm install`\n3. Open in VS Code\n4. Press F5 to launch Extension Development Host\n5. Test your changes\n\n### AI-Assisted Development (Optional)\n\nThis 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.\n\n**Setup:**\n\n1. Copy `.env.example` to `.env`:\n   ```bash\n   cp .env.example .env\n   ```\n\n2. Get your Context7 API key from [context7.com](https://context7.com)\n\n3. Add your API key to the `.env` file:\n   ```\n   CONTEXT7_API_KEY=your-api-key-here\n   ```\n\n4. The MCP server is already configured in `.mcp.json`\n\n**Available Slash Commands:**\n\nThe project includes custom slash commands for on-demand documentation retrieval:\n\n- `/context7:vscode [topic]` - Pull VS Code Extension API docs and samples\n  - Example: `/context7:vscode FileSystemWatcher`\n  - Example: `/context7:vscode` (general context)\n\n- `/context7:kirby [topic]` - Pull Kirby CMS documentation\n  - Example: `/context7:kirby blueprints`\n  - Example: `/context7:kirby` (general context)\n\n- `/context7:full [topic]` - Pull both VS Code and Kirby docs (comprehensive context)\n  - Example: `/context7:full template validation`\n  - Example: `/context7:full` (general context from both sources)\n\n**When to use Context7 commands:**\n- ✅ Working with unfamiliar or new APIs\n- ✅ Troubleshooting complex issues\n- ✅ Implementing features requiring deep understanding of both systems\n- ✅ Verifying best practices or API changes\n- ❌ Following existing patterns (usually not needed)\n- ❌ Routine refactoring or similar features\n\n**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.\n\n### Building \u0026 Testing\n\n```bash\nnpm run compile      # Compile TypeScript + copy schemas\nnpm run watch        # Watch mode for development\nnpm run lint         # Run ESLint validation\nnpm run test         # Run all 284 tests (compile + lint + test suite)\n```\n\n**Quality Assurance:**\n- All commits are automatically tested via pre-commit hooks\n- Tests must pass before code can be committed\n- 284 tests covering security, parsing, scaffolding, refactoring, navigation, integration, and build automation\n- Zero tolerance for security vulnerabilities\n\n### Packaging\n\n```bash\nnpm install -g @vscode/vsce\nvsce package\n```\n\n## License\n\nThis extension is licensed under the MIT License.\n\n### Bundled Dependencies\n\n- **Kirby Blueprint JSON Schema**: MIT License © [bnomei](https://github.com/bnomei) - The complete license is bundled with this extension in [src/schemas/LICENSE](src/schemas/LICENSE). Original repository: [bnomei/kirby-schema](https://github.com/bnomei/kirby-schema)\n- **js-yaml**: MIT License © Vitaly Puzrin - Used for parsing Blueprint YAML files\n\n## Acknowledgments\n\n- [Kirby CMS](https://getkirby.com) - The amazing file-based CMS\n- [bnomei](https://github.com/bnomei) - For the Kirby Blueprint JSON Schema\n- The Kirby community for inspiration and feedback\n\n## Support\n\n- **Issues**: [Report bugs or request features](https://github.com/MichaelvanLaar/vscode-kirby-toolkit/issues)\n- **Security**: [Report vulnerabilities](SECURITY.md#reporting-a-vulnerability)\n- **Kirby Forum**: Join the discussion at [forum.getkirby.com](https://forum.getkirby.com)\n\n---\n\n**Enjoy developing with Kirby CMS!** 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelvanlaar%2Fvscode-kirby-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichaelvanlaar%2Fvscode-kirby-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelvanlaar%2Fvscode-kirby-toolkit/lists"}