
XSLT/XPath for Visual Studio Code
The XSLT/XPath extension for VS Code provides comprehensive language support for XSLT 3.0 and XPath 3.1, and for the XSLT 4.0 and XPath 4.0 features implemented in Saxon 13.
The aim is to make writing, reviewing and debugging XSLT easier. The extension understands each XPath expression - which names are variables, functions or node tests, and where each is declared, including in imported modules - so problems show as you type, and you can go from any name to its declaration, rename it safely, or step through the expression in the debugger.
Getting started:
- Install the extension and open an XSLT file - editing, highlighting and linting need no setup.
- To run or debug stylesheets, set
XSLT.tasks.saxonJar to the path of your Saxon jar (Saxon-HE is fine), with a Java runtime on the PATH.
- Press Quick Run (
⌘⌥R / Ctrl+Alt+R) to run the stylesheet with the XML file you last had open - shown in the status bar, where you can pick another.
See the XSLT/XPath User Guide for the full description of each feature.
Debugging XSLT with SaxonJ: paused within an XPath expression, with its range variable,
the context and global variables, inline values and the call stack:
Features
The step-through XSLT debugger for SaxonJ sets breakpoints and steps through templates, functions and multi-line XPath expressions - including inline functions passed to functions such as fold-left - showing variables and the context item as you go.
- XSLT 3.0 and XPath 3.1
- XSLT 4.0 and XPath 4.0, as in
Saxon 13
- XSpec - first-class language intelligence
- SaxonJS interactive extensions (IXSL)
- Open XPath editor for the active XML file
- Fast semantic highlighting
|
- Record and enum types, with type-aware checks
- Named item types:
xsl:item-type
- Full language features for JNodes (JSON)
xsl:switch, with missing-case quick fixes
- Keyword arguments and optional parameters
- Functions in no namespace
|
- Context-aware auto-completion, incl. node names
- Signature help and hover help
- Snippets, incl. new stylesheets for 3.0 and 4.0
- Formatting of instructions and multi-line XPath
- Rename symbol, across imported modules
- Semantic highlighting from a full XPath parser
- Code actions for Quick-Fix and Refactoring
|
- Step-through XSLT debugger (SaxonJ)
- Per-line tracing of multi-line XPaths
- Conditional Breakpoints or Logpoints
- Views for globals, locals, context and output
- Watch expressions and debug console
- Output node mapping to its XSLT origin
- Formatted and colorised print debugging
|
- XPath syntax and XSLT instructions
- Types, records, enums and function arguments
- Unused XSLT and XPath variables or parameters
- References across imported modules
- Saxon errors from runs, in the Problems panel
- Quick fixes for common problems
- MCP server for AI assistants (experimental)
|
- Go to (or peek) definition, and find references
- Go to the declarations of record fields
- Outline, breadcrumbs and Go to Symbol
- Find nodes in XML with a fully featured XPath editor
- Links for
xsl:import and xsl:include
- XSLT Imports view, with inferred top-level stylesheets
- Filterable dropdown listing all symbols and modes
|
- Context-aware with safe symbol renaming
- Extract
xsl:function or xsl:template
- Extract
xsl:variable from an XPath expression
- Extract a record type from a map
- Wrap with... an instruction (
⌥⇧W / Alt+Shift+W)
- Add a documentation note
|
- Quick Run (
⌘⌥R / Ctrl+Alt+R)
- Tasks for SaxonJ, SaxonJS and SaxonC
- Required
xsl:param values asked for when a task runs
xsl:param values controlled by tasks
- XML catalogs for
xsl:import URIs
- File pickers for task inputs
|
xsl:note with Markdown and xqDoc-style tags
- Shown in hover and signature help
@see references, with navigation and rename
- Checks of
@param and @field tags
- Module notes for stylesheets
- Highlighting and auto completion for tags or references
|
- XSpec 4.1.2 test framework built in
- Run, debug and run with coverage from Test Explorer
- Advanced language support within XSpec editor
- Add debug breakpoints direct in XSpec file
- Generate XSpec tests for functions or templates
- Navigate between tests and the associated XSLT
|
XSLT 4.0 with a documentation note, its hover help where the function is called, and the XSLT Imports view:
XML Commands
The XML selection commands are also in the XML Selection submenu of the editor's context menu (right-click), and in the XML: Select Element... quick pick (⇧⌘2 / Ctrl+Shift+2) - both show their key-bindings.
| Command |
Key-Binding (macOS / Windows, Linux) |
Details |
| XML: Find Nodes with XPath... |
|
Opens the XPath query file below the XML file |
| XML: Add XPath Location to Queries |
⌥G / Alt+G |
Adds the location of the node at the cursor to the XPath query file |
| XML: Select Element... |
⇧⌘2 / Ctrl+Shift+2 |
Quick pick of the XML selection commands, and the XPath query commands |
| XML: Select current element |
⇧⌘0 / Ctrl+Shift+0 |
Includes start/end tags |
| XML: Select parent element |
⇧⌘9 / Ctrl+Shift+9 |
Includes start/end tags |
| XML: Select first child element |
⇧⌘8 / Ctrl+Shift+8 |
Includes start/end tags |
| XML: Select following element |
⇧⌘7 / Ctrl+Shift+7 |
Includes start/end tags |
| XML: Select preceding element |
⇧⌘6 / Ctrl+Shift+6 |
Includes start/end tags |
| New XPath Notebook |
- |
DeltaXignia's XPath Notebook extension is required |
Introduction
For lexical analysis, this extension processes code character-by-character, and every feature - including all syntax highlighting - uses the result. This keeps editing responsive, and the highlighting accurate even in long, multi-line XPath expressions.
Auto-completion is provided for XSLT and XPath. This includes context-aware completion items for all code symbol names. XSLT and XPath function signatures and descriptions are shown in the description alongside function completion items. The last active non-XSLT file is used as the source to compute available node names for XPath location steps.
This extension's linter performs a comprehensive set of checks on the code. The linter ensures that any code symbols within XSLT or XPath with problems are accurately identified at the symbol-level. Asynchronous processing for xsl:include/xsl:import dependencies allows checking of references to symbol definitions regardless of the location of the definition.
Running XSLT

(1) XSLT in active editor, (2) the Saxon processor, (3) the XML context file - click the play button to run
The quickest way to run the stylesheet in the active editor is Quick Run (⌘⌥R / Ctrl+Alt+R): the first run creates a task for you, which later runs reuse.
XSLT transforms for SaxonJ, SaxonJS and SaxonC are configured and run as special VS Code tasks.
XSLT task JSON properties can reference special commands. The special commands allow file-selection via a File Explorer or 'Recent Files' list, an example using: "xsltFile": "${command:xslt-xpath.pickXsltFile}". The XSLT: Add XSLT Inputs to Tasks File command adds inputs for file-selection prompts to tasks.json. A sample screenshot is shown below:

For a full description of using VS Code tasks to run XSLT, see Running XSLT.
Debugging XSLT
Stylesheets can be debugged with SaxonJ (Saxon 12 or later, any edition, including Saxon-HE): set breakpoints in the stylesheet, then use XSLT: Debug Stylesheet with SaxonJ (the debug button in the editor title, or F5 with no launch.json). The stylesheet runs as Quick Run runs it - with the XML context file, or from xsl:initial-template - using the Quick Run task's settings.
Where Saxon's standard tracing stops at XSLT instructions, this debugger uses Saxon's own APIs to inject extra trace points and re-parse XPath to locate sub-expressions, so it can stop deep inside multi-line expressions and inline functions.
- Add debugger breakpoints or logpoints to almost any line of interest - from an XSLT instruction to deep within an XPath sub expression or inline function
- Line breakpoints, with conditions, hit counts and logpoints (
{$*} in a logpoint's message logs the local variables) - and function breakpoints, for stylesheet functions and named templates
- Step Over, Step Into and Step Out - including line by line through multi-line XPath expressions, and into inline functions
- Local and global variables, the context item,
current-group() and regex-group() - and their values inline, while paused
- XPath evaluation in the Watch view, the Debug Console and on hover, where execution is paused
- Pause execution on dynamic errors, and the output written so far
See XSLT Debugger in the User Guide for the full description - including launch.json configurations, limitations and troubleshooting.
Release Notes
The project changelog is maintained on the project wiki. See Release Notes.
Extension Settings
Editing and linting need no settings. Running and debugging stylesheets need the path of a Saxon processor (see below).
This section outlines the main settings associated with XSLT features.
For more details on how these settings are managed within VS Code see: VS Code Settings
XSLT Tasks
To use the task-provider for the Java Saxon XSLT Processor, the following setting is required (alter path to suit actual jar location):
"XSLT.tasks.saxonJar": "/path/to/folder/SaxonHE12-9J/saxon-he-12.9.jar"
To use the task-provider for SaxonC, set the path of the folder containing the SaxonC command-line Transform executable:
"XSLT.tasks.saxonCPath": "/path/to/folder/containing/Transform"
XSLT 4.0 Tasks
XSLT 4.0 requires Saxon-PE or Saxon-EE (or the equivalent SaxonC edition). The task property allowSyntaxExtensions40 defaults to "auto", which enables XPath 4.0 syntax unless the processor is Saxon-HE.
When the parse-html() function is used, the following setting is also needed, e.g.:
"XSLT.tasks.htmlParserJar": "/path/to/folder/htmlparser-1.4.jar" // or: nu.validator.jar
XSLT Packages
If your XSLT contains xsl:use-package instructions, XSLT package names are resolved to lookup symbols to support the following features:
- Goto Definition
- Symbol Diagnostics
- Symbol Auto-Completion
To allow XSLT package names to be resolved to file paths, package details should be added to the setting:
XSLT.resources.xsltPackages
An example of XSLT package name settings:
"XSLT.resources.xsltPackages": [
{ "name": "example.com.package1", "version": "2.0", "path": "included1.xsl"},
{ "name": "example.com.package2", "version": "2.0", "path": "features/included2.xsl"},
{ "name": "example.com.package3", "version": "2.0", "path": "features/not-exists.xsl"}
]
If file paths are relative they are resolved from the first Visual Studio Code Workspace folder
Note: Currently, XSLT Package versions are not used in package-name lookup
This extension supports special XSLT code formatting. This can be invoked with a VS Code command and/or as you type, depending on your settings.
- On Windows -
Shift + Alt + F.
- On Mac -
Shift + Option + F.
- On Ubuntu -
Ctrl + Shift + I.
You should start with something like the following in the settings.json file:
{
...
"[xslt]": {
"editor.formatOnPaste": true,
"editor.formatOnSave": false,
"editor.formatOnSaveMode": "modifications",
"editor.formatOnType": true,
"editor.defaultFormatter": "deltaxml.xslt-xpath",
"editor.detectIndentation": true,
"editor.tabSize": 2,
"editor.wordSeparators": "`~!@#$%^&*()=+[{]}\\|;:'\",.<>/?",
"outline.showArrays": true,
"breadcrumbs.showArrays": true,
"editor.semanticHighlighting.enabled": true
}
...
}
Refactoring
A range of code refactoring features are supported, including Rename Symbol, Extract Function and, for XSLT 4.0, Extract record type.
When XSLT code is refactored, instructions and expressions are revised when necessary to
ensure the code behaviour remains unchanged. For example, the Extract Function refactor revises all expressions requiring the context-item so the code compiles and runs as before.
Editor Settings for Highlighting in Color Theme Extensions
Syntax highlighting is currently only enabled by default in VS Code's built-in themes. This is because some extension themes may not yet have specific language support for VS Code's 'Semantic Highlighting' as used by this extension.
To enable syntax highlighting for a custom theme you need to change User Settings. A set of dark color themes, specially enhanced
for XSLT, are provided by the XSLT Dark Themes extension.
You can also customize
XSLT token colors. For example, to enable syntax highlighting for XSLT and add some customizations in the Gruvbox Material Dark theme you could use:
"editor.semanticTokenColorCustomizations": {
"[Gruvbox Material Dark]": {
"enabled": true,
"rules": {
"xmlPunctuation": "#b75a1e",
"anonymousFunction": "#d3869b",
"xmlText": "#928374",
"attributeNameTest": "#89b482",
"elementName": "#d3869b"
},
}
},
Or, to enable syntax highlighting for all themes:
"editor.semanticHighlighting.enabled": true,
Editor Settings For Word Selection/Navigation
As in XPath, a name like $two-parts, f:line-total or xsl:value-of is one word for completion, the debugger's hovers, highlighting its other occurrences and finding it (e.g. Cmd+D / Ctrl+D).
For word selection and navigation (e.g. double-click, or Alt/Ctrl + arrow keys), the extension's default editor.wordSeparators setting keeps names like two-parts together, but separates $ and a prefix's :. This behaviour can be altered using the VS Code setting:
editor.wordSeparators
See: VS Code Documentation on Settings
Code Folding
Code-folding currently works by indentation indicating the nesting level. So, if code-folding does not work as expected, try reformatting using (for MacOS) - Shift-⌥-F.
Region code-folding is also supported. This can be useful, for example, for blocks of templates for a specific mode. To set a region code-folding block, surround it with <?region?> and <?endregion?> processing instructions. You may optionally include a label for the processing instructions, for example:
<?region reconstruct?>
...
<?endregion reconstruct?>
XSLT/XPath User Guide
The XSLT/XPath User Guide provides an introduction to features supported by this extension for XSLT and XPath developers.
The main documentation pages are linked below:
Support for other languages with embedded XPath
In addition to XSLT, XPath embedded in these XML vocabularies is highlighted, checked and auto-completed:
Project Sponsor Message:

DeltaXignia specialise in management of change in structured content with solutions including XML and JSON compare and merge. Whether you are working with documents, data or code, DeltaXignia’s solutions provide the most reliable, efficient and accurate comparison and merge functions for managing structured content.
Comprehensive API’s, configurable output formats and full audit trail capabilities make DeltaXignia’s products perfect for integration with your current content management workflows or for embedding within existing editing and publishing products.