Twig Go to Definition
A VS Code extension that provides "Go to Definition" functionality for Twig template files using the Language Server Protocol.
Features
This extension adds intelligent navigation support for Twig templates:
- Template Navigation: Click on template names in
{% extends %}
and {% include %}
statements to jump to the referenced template file
- Block Navigation: Navigate from block references to their definitions in parent templates
- Parent Call Navigation: Navigate from
{{ parent() }}
calls to the parent template's block definition
- Block Function Navigation: Navigate from
{{ block('name') }}
calls to block definitions
- Variable References: Navigate to variable definitions within templates
- Auto-completion: Intelligent completion for template names, block names, variables, and Twig tags with configurable path resolution and smart filtering
- Find All References: Locate all usages of templates, blocks, and variables across your project
- Template Outline: Document symbol provider showing template structure (blocks, includes, variables) in the outline view
- Hover Information: Detailed information about templates, blocks, and variables on hover
- Diagnostics: Real-time validation of template references and syntax
- Automatic File Discovery: Intelligent resolution of template paths across common Twig project structures
- Configurable Path Resolution: Choose between smart, absolute, or relative path suggestions in autocomplete
- Customizable Template Directories: Configure which folders to search for templates
Supported Twig Features
{% extends "template.twig" %}
- Navigate to parent template
{% include "partial.twig" %}
- Navigate to included template
{% block content %}
- Navigate to block definitions in parent templates
{{ parent() }}
- Navigate to parent template's block definition
{{ block('name') }}
- Navigate to block definitions
- Variable references in
{{ variable }}
syntax
- Variable definitions in
{% set %}
and {% for %}
loops
- Find All References - Right-click to find all usages of templates, blocks, or variables
- Template Outline - View template structure in VS Code's outline panel
- Template and block auto-completion with smart filtering
- Real-time error detection for missing templates and blocks
Requirements
- VS Code 1.90.0 or higher
- Twig template files with
.twig
or .html.twig
extensions
Extension Settings
This extension contributes the following settings:
twigGoToDefinition.pathResolution
- Type:
string
- Default:
"smart"
- Options:
"smart"
, "absolute"
, "relative"
- Description: Controls how template paths are suggested in autocomplete
- Smart: Use relative paths within same top-level folder, absolute paths for cross-folder references
- Absolute: Always use full paths from workspace root (e.g.,
examples/base.twig
)
- Relative: Always use relative paths from current file (e.g.,
../base.twig
)
twigGoToDefinition.templateDirectories
- Type:
array
- Default:
["templates", "views", "src/templates", "examples"]
- Description: Additional directories to search for Twig templates
twigGoToDefinition.diagnostics.enabled
- Type:
boolean
- Default:
true
- Description: Enable error checking for missing templates and blocks
Usage
Accessing Settings
- Open VS Code Settings (
Ctrl+,
/ Cmd+,
)
- Search for "Twig Go to Definition"
- Configure your preferred path resolution and template directories
Path Resolution Examples
When editing examples/components/content-section.twig
:
Smart Mode (default):
- Same directory:
section-footer.twig
- Parent folder:
../base.twig
- Different top-level:
templates/layout.twig
Absolute Mode:
- Same directory:
examples/components/section-footer.twig
- Parent folder:
examples/base.twig
- Different top-level:
templates/layout.twig
Relative Mode:
- Same directory:
./section-footer.twig
- Parent folder:
../base.twig
- Different top-level:
../../templates/layout.twig
Template Path Resolution
The extension provides intelligent template path resolution with multiple strategies:
Default Search Directories
The extension automatically searches for templates in these directories:
- Relative to current file
templates/
directory
views/
directory
src/templates/
directory
app/Resources/views/
directory (Symfony)
examples/
directory (for testing)
- Workspace root
Path Resolution Strategies
Smart Resolution (Default):
- Uses the most intuitive path for each context
- Same directory: just filename
- Same top-level folder: relative path
- Different folders: absolute from workspace root
Absolute Resolution:
- Always shows full path from workspace root
- Consistent absolute references
- Best for large projects with complex folder structures
Relative Resolution:
- Always shows path relative to current file
- Traditional relative path behavior
- Best for developers who prefer explicit relative paths
Configurable Template Directories
You can customize which directories the extension searches by modifying the twigGoToDefinition.templateDirectories
setting.
Known Issues
- Variable reference navigation is limited to local template scope
- Complex Twig expressions may not be fully supported
- Performance may be impacted with very large template hierarchies
- Some edge cases in deeply nested template inheritance may not be fully supported
Troubleshooting
Common Issues
Templates not found in autocomplete:
- Check that templates are in configured directories (
twigGoToDefinition.templateDirectories
)
- Verify file extensions are
.twig
or .html.twig
- Check VS Code Output panel → "Twig Language Server" for path resolution details
Go to Definition not working:
- Ensure the template file exists and is readable
- Check the Output panel for error messages
- Verify template paths match the configured resolution strategy
Autocomplete showing wrong paths:
- Adjust the
twigGoToDefinition.pathResolution
setting
- Customize
twigGoToDefinition.templateDirectories
for your project structure
Debugging
Enable detailed logging by checking the Output panel:
- Open Output panel (
View > Output
)
- Select "Twig Language Server" from dropdown
- Trigger the feature to see detailed logs
Release Notes
0.0.7
Quality of life improvements and enhanced navigation:
- Smart Autocomplete Filtering: Template suggestions now filter as you type with fuzzy matching
- Find All References: Right-click on templates, blocks, or variables to find all usages across your project
- Template Outline View: Document symbol provider shows template structure in VS Code's outline panel
- Enhanced Completion Scoring: Better sorting of autocomplete suggestions based on relevance
- Improved Reference Detection: More accurate template and block reference finding
- Performance Optimizations: Better handling of large template hierarchies
0.0.6
Added comprehensive configuration system:
- Configurable Path Resolution: Choose between smart, absolute, or relative path suggestions
- Customizable Template Directories: Configure which folders to search for templates
- Settings Integration: Full VS Code settings integration with live configuration updates
- Enhanced Autocomplete: Context-aware path suggestions based on current file location and settings
- Improved Path Intelligence: Better handling of same-directory and cross-directory template references
0.0.5
Major improvements to autocomplete and path resolution:
- Smart Path Suggestions: Intelligent path resolution based on file location context
- Enhanced Autocomplete: Improved template name completion with better sorting and context
- Same-Directory Optimization: Prioritized suggestions for files in the same directory
- Cross-Directory Intelligence: Smart handling of templates across different project folders
- Extensive Debugging: Added comprehensive logging for troubleshooting path resolution
0.0.4
Enhanced implementation with comprehensive feature support:
- Added navigation for
{{ parent() }}
calls to parent template blocks
- Added navigation for
{{ block('name') }}
function calls
- Implemented variable reference navigation within templates
- Added intelligent auto-completion for templates, blocks, variables, and Twig tags
- Added hover information with detailed context
- Added real-time diagnostics for template validation
- Improved template path resolution with better error handling
- Enhanced block navigation across template inheritance chains
- Added support for variable definitions in
{% set %}
and {% for %}
statements
0.0.1
Initial release with basic Go to Definition support:
- Navigate to templates referenced in
{% extends %}
statements
- Navigate to templates referenced in
{% include %}
statements
- Navigate to block definitions in parent templates
- Basic Twig syntax highlighting
- Language configuration for Twig files
Development
To run this extension in development:
- Open this project in VS Code
- Press
F5
to open a new Extension Development Host window
- Create or open Twig files to test the functionality
- Use
Ctrl+Click
(or Cmd+Click
on macOS) on template names or block names to test navigation
Contributing
This extension is open source. Feel free to contribute improvements and bug fixes.
License
MIT License - see LICENSE file for details
Enjoy!