Settings
Visual Studio Code's settings let you tailor your working environment to fit requirements for specific languages or extensions, or to suit your own preferences.
A general guide to settings is provided by the Visual Studio Code documentation: User and Workspace Settings. This page lists the XSLT/XPath extension's own settings, and the editor settings of most interest for XSLT and XPath.
Creating User and Workspace Settings
From the Command Palette (⇧⌘P) you can either invoke
Preferences: Open User Settings or Preferences: Open Workspace Settings. Editor
settings can also be applied in a language-specific way: for this, use the command
Preferences: Configure Language Specific Settings.
Settings are either edited in the Settings form or in a JSON editor. Open the JSON editor by clicking the
Open Settings (JSON) button at the top right of the Editor Group. This opens the
corresponding settings.json file directly.
User settings apply wherever you use VS Code, so they suit paths on your own computer, such as the Saxon
jar. Workspace settings are saved in the project's .vscode/settings.json and apply to everyone
who opens the project, so they suit settings a team shares, such as an XML catalog or XSLT packages.
XSLT/XPath Extension Settings
To list the extension's settings in the Settings editor, type XSLT in its search box. All of
them are listed below, with their defaults. The sections after the tables describe the most important ones.
Running and debugging
| Setting | Default | What it does |
|---|---|---|
XSLT. |
- | The path of your Saxon jar file, needed to run or debug stylesheets with SaxonJ - see The Saxon jar. |
XSLT. |
"xslt" |
The processor Quick Run uses: "xslt" (SaxonJ),
"xslt-js" (SaxonJS) or "xslt-c" (SaxonC). Switching processor in Quick Run
saves the choice here. |
XSLT. |
true |
Offer SaxonJ (xslt) tasks - see Task types. |
XSLT. |
true |
Offer SaxonJS (xslt-js) tasks. |
XSLT. |
true |
Offer SaxonC (xslt-c) tasks. |
XSLT. |
- | The folder containing the SaxonC command-line executable (Transform or
Transform.exe) - see SaxonC tasks. |
XSLT. |
- | The path of SaxonC's saxon-license.lic file, passed to SaxonC as
--licenseFileLocation: - see Licensing. |
XSLT. |
- | More folders to search for SaxonC's native libraries. The lib folder beside the
executable is always included - see
Native library path. |
XSLT. |
- | The path of the nu.validator
htmlparser jar, added to SaxonJ's classpath for XSLT 4.0 stylesheets, for Saxon's
parse-html() function. |
XSLT. |
false |
When debugging, open the output written so far beside the stylesheet, at the first pause where there is some - see Output while debugging. |
Editing and checking
| Setting | Default | What it does |
|---|---|---|
XSLT. |
"" |
An OASIS XML catalog file, for resolving the href of xsl:import and
xsl:include - also passed to Saxon - see XML catalog. |
XSLT. |
- | The files for xsl:use-package names - see XSLT packages. |
XSLT. |
true |
For a module that another stylesheet imports or includes, find that stylesheet from the workspace's files, so references to its declarations are resolved without opening it first - see Inferred imports. |
XSLT. |
"latest" |
Completion of element and attribute names in XPath: "latest" suggests the names that
can occur at that point in the path, from the XML context file; "none" suggests the names
already used in the stylesheet - see
IntelliSense for XPath locations. |
XSLT. |
[] |
Prefixes of functions the processor provides, such as Java extension functions - calls of functions with these prefixes aren't checked. The quick fix for a function that isn't found adds its prefix - see Java extension functions. |
XSLT. |
false |
Allow XSLT 4.0 named item types and xsl:note in XSLT 3.0 stylesheets, for Saxon PE and
EE 12.8 or later - see below. |
XSLT. |
false |
Warn in every stylesheet before XSLT 4.0 about union patterns whose branches have different default priorities - not only where XSLT 4.0's rule applies already - see Union patterns and XSLT 4.0. |
XSpec tests
| Setting | Default | What it does |
|---|---|---|
XSLT. |
- | The folder of another XSpec installation, e.g. a newer release, to compile and run tests with - by default the XSpec 4.1.2 included. See XSpec tests. |
XSLT. |
"auto" |
Run tests with Saxon's syntax extensions (--allowSyntaxExtensions:on), so the stylesheet tested can use XPath 4.0 syntax, or e.g. record types in an XSLT 3.0 stylesheet: "auto" - on only for tests of a stylesheet that's XSLT 4.0, or uses item types or notes, and not with Saxon-HE, which fails every transform with them on - "on" or "off". See XSpec tests. |
XSLT. |
false |
Run tests written for XSpec before 1.0 (e.g. 0.5) as that ran them, where XSpec 4 stops the run - see Tests written for older XSpec. |
XSLT. |
true |
In XSpec files, show scenario labels in bold and expectation labels in italic, so the scenarios read like headings. |
XSLT. |
true |
In XSpec files, fade the pending scenarios and expectations, other than the reason they're pending. |
AI assistants
| Setting | Default | What it does |
|---|---|---|
XSLT. |
false |
Run the extension's MCP server, with tools for AI assistants such as GitHub Copilot and Claude Code - see The MCP server. |
XSLT. |
6745 |
The port the MCP server listens at, on 127.0.0.1. With more than one window open, the first
one opened has the server. |
The Saxon jar
To run or debug stylesheets with SaxonJ - Saxon for Java - set XSLT.tasks.saxonJar to the full
path of your Saxon jar file, usually as a user setting, since the path is specific to your computer. Any
Saxon edition works, including Saxon-HE. The Debugger needs Saxon 12 or later,
and a Java runtime must be on the PATH:
"XSLT.tasks.saxonJar": "/Users/me/saxon/SaxonHE12-9J/saxon-he-12.9.jar"
On Windows, write each \ in the path as \\, as JSON requires - e.g.
"C:\\saxon\\saxon-he-12.9.jar". For Saxon-PE or Saxon-EE, keep the licence file,
saxon-license.lic, in the same folder as the jar.
XSLT tasks refer to the setting as ${config:XSLT.tasks.saxonJar}. For downloading Saxon and
Java, see SaxonJ tasks.
XSLT packages
Packages in the workspace are found without a setting. For a package outside the workspace, add its path
to XSLT.resources.xsltPackages - its name and version are read from its
xsl:package element. See XSLT Packages.
"XSLT.resources.xsltPackages": [
{ "path": "../shared-xslt/strings.xsl" }
]
XML catalog
To resolve the href of xsl:import and xsl:include - and the URIs of
fixed-namespaces - with an OASIS XML catalog, and pass the catalog to Saxon when a stylesheet is
run, set XSLT.resources.catalog to the catalog file's path, relative to the workspace folder.
See XML Catalogs.
"XSLT.resources.catalog": "catalog.xml"
Task types
The extension provides a task type for each Saxon processor - xslt for SaxonJ,
xslt-js for SaxonJS and xslt-c for SaxonC - and all three are enabled by default.
To stop a processor's tasks being offered, for example in Run Build Task, turn off its
setting:
"XSLT.tasks.java.enabled": true,
"XSLT.tasks.js.enabled": true,
"XSLT.tasks.saxonc.enabled": true
See Tasks for configuring each task type.
XSLT 4.0 Item Types and Notes in XSLT 3.0
Saxon PE and EE 12.8 or later, run with syntax extensions, accept XSLT 4.0's named item types and
xsl:note in a stylesheet with version="3.0". To edit such stylesheets with the
same support as for XSLT 4.0, enable the setting XSLT.validation.xslt30ItemTypesAndNotes - it's
off by default. For a team, add it to the workspace settings, in the project's
.vscode/settings.json:
"XSLT.validation.xslt30ItemTypesAndNotes": true
With the setting, in an XSLT 3.0 stylesheet:
xsl:item-typedeclarations are accepted, withrecord(...)andenum(...)types - which can also be used directly inasattributes- the record and enumeration type support applies: completions of record fields, map keys and enumeration values, checks of map constructors, lookups and values, hover help, and renaming a record field
xsl:noteneeds nouse-whenattribute - see Code Documentation
Other XSLT 4.0 and XPath 4.0 features - such as xsl:switch, keyword arguments and
fn(...) types - still need version="4.0", and are reported as errors in an XSLT
3.0 stylesheet.
Without the setting, xsl:item-type and record and enumeration types are reported as errors in
an XSLT 3.0 stylesheet, and an xsl:note gets a warning unless it's excluded with
use-when="false()", as an XSLT 3.0 processor reports XTSE0010 for it.
To run the stylesheets, Saxon needs syntax extensions: the --allowSyntaxExtensions:on option on
the command line, or allowSyntaxExtensions="true" in a Saxon configuration file. The
extension's XSLT tasks and Quick Run enable it
with the default "allowSyntaxExtensions40": "auto" task property, for Saxon PE and EE, when the
stylesheet - or a module it imports, includes or uses - has item types or notes.
Converting Saxon type aliases
Saxon's earlier syntax for named types - saxon:type-alias, tuple(...) types and
~name for a reference to a type alias - is ignored by Saxon 12.8 and later, which only report
the references. The linter warns about a saxon:type-alias, and the command
XSLT: Convert Saxon Type Aliases to xsl:item-type - also the warning's quick fix - converts
them in all the workspace's files, shown for review in the refactor preview first:
<saxon:type-alias name="dfx:bounds" type="..."/>becomes<xsl:item-type name="dfx:bounds" as="..."/>tuple(t: xs:integer, label?: xs:string)becomesrecord(t as xs:integer, label? as xs:string)as="~dfx:bounds"becomesas="dfx:bounds"
A type alias with an extensible tuple type, e.g. tuple(a: xs:string, *), isn't converted - nor
is one that references it - as XSLT 4.0 has no extensible record types. These are listed after the
conversion, to convert by hand.
General Settings for XSLT
Default Editor Settings for XSLT, XPath and XML
The extension sets these VS Code editor settings for the xslt, xpath and
xml languages - for .xsl, .xslt, .xpath and XML files. As
they're set for each language, they don't affect files in other languages. Any of them can be changed in a
language-specific setting, e.g. "[xslt]": { "editor.tabSize": 4 } - see
Creating User and Workspace Settings.
| Setting | XSLT and XPath | XML | What it does |
|---|---|---|---|
editor. |
"deltaxml.xslt-xpath" |
This extension formats the file - see Code Formatting. | |
editor. |
true |
Lines are indented as you type, e.g. a new line, or a closing tag. | |
editor. |
true |
Pasted text is indented to fit where it's pasted. | |
editor. |
false |
The file isn't formatted when it's saved. | |
editor. |
"file" |
If formatOnSave is turned on, the whole file is formatted - or only the lines
changed, with "modifications". |
|
editor. |
2 |
4 |
The number of spaces for each level of indentation. |
editor. |
true |
Indentation uses spaces, not tabs. | |
editor. |
true |
For an existing file, the tab size and spaces or tabs are detected from its content, instead of the two settings above. | |
editor. |
"`~!@#%^&*()=+[{]}\\|;'\",:<>/?$" |
Unlike VS Code's default, - and . aren't word separators, so
double-clicking selects a whole name, such as current-group - see
Word Separators. |
|
editor. |
true |
- | Syntax highlighting for XSLT and XPath, which uses semantic tokens - see
Syntax Highlighting. It's also set for the xsl
language. |
outline. |
false |
The Outline view doesn't show arrays - see Code Navigation. | |
The default settings, as JSON
"[xslt]": {
"editor.defaultFormatter": "deltaxml.xslt-xpath",
"editor.formatOnSaveMode": "file",
"editor.formatOnSave": false,
"editor.formatOnPaste": true,
"editor.formatOnType": true,
"editor.semanticHighlighting.enabled": true,
"editor.detectIndentation": true,
"editor.wordSeparators": "`~!@#%^&*()=+[{]}\\|;'\",:<>/?$",
"editor.insertSpaces": true,
"editor.tabSize": 2,
"outline.showArrays": false
},
"[xpath]": {
"editor.defaultFormatter": "deltaxml.xslt-xpath",
"editor.formatOnSaveMode": "file",
"editor.formatOnSave": false,
"editor.formatOnPaste": true,
"editor.formatOnType": true,
"editor.semanticHighlighting.enabled": true,
"editor.detectIndentation": true,
"editor.wordSeparators": "`~!@#%^&*()=+[{]}\\|;'\",:<>/?$",
"editor.insertSpaces": true,
"editor.tabSize": 2,
"outline.showArrays": false
},
"[xml]": {
"editor.defaultFormatter": "deltaxml.xslt-xpath",
"editor.formatOnSaveMode": "file",
"editor.formatOnSave": false,
"editor.formatOnPaste": true,
"editor.formatOnType": true,
"editor.wordSeparators": "`~!@#%^&*()=+[{]}\\|;'\",:<>/?$",
"editor.detectIndentation": true,
"editor.insertSpaces": true,
"editor.tabSize": 4,
"outline.showArrays": false
},
"[xsl]": {
"editor.semanticHighlighting.enabled": true
}
Built-in Editing Behaviour for XSLT
The extension also defines how the editor treats XSLT files in ways that aren't settings, so they can't be changed:
- Comments - Toggle Block Comment (⇧⌥A)
wraps the selection in
<!--and-->. In.xpathfiles it uses XPath's(:and:). - Auto-closing - typing
{,[,(, a quote or a backtick adds the closing character. So does&, which adds;for an entity reference, and(:, which adds:to start an XPath comment. - Surrounding - typing one of these characters with text selected surrounds the
selection with the pair, e.g. selecting
$totaland typing(gives($total). - Words - a prefixed name such as
xsl:template, a variable reference such as$total-price, and an attribute name test such as@selecteach count as one word - for example, when VS Code finds the word at the cursor for word-based suggestions. - Folding regions -
<?region?>and<?endregion?>processing instructions mark a region that can be folded - see Folding.
Code Formatting
The following settings directly affect code formatting in the XSLT/XPath extension:
"editor.defaultFormatter": "deltaxml.xslt-xpath",
"editor.formatOnSaveMode": "modifications",
"editor.formatOnSave": true,
"editor.formatOnPaste": true,
"editor.formatOnType": true
The editor.formatOnSaveMode setting can be used to only format XSLT lines changed since the
last commit on Git.
Syntax Highlighting
Syntax highlighting for XSLT and XPath is achieved using Visual Studio Code's Semantic Highlighting tokens alone. Almost all other languages in Visual Studio Code use a TextMate Grammar for tokens, which may be supplemented by Semantic Highlighting.
If XSLT and XPath are not syntax highlighted in a Color Theme, you can explicitly enable Semantic Highlighting with the setting:
"editor.semanticHighlighting.enabled": true
The XSLT Dark Themes extension provides a selection of popular dark color themes, enhanced for XSLT/XPath.
Screenshot of Gruvbox Theme extended for XSLT
Word Separators
The editor.wordSeparators setting affects how the full 'word' is selected when you double-click
on a part of the word. The characters listed are used as word separators. Typically in XSLT, you do not want
characters like - and . treated as word separators, as these characters are valid
within a QName like an attribute name or a variable name.
The Agents Window
Visual Studio Code's Agents window only runs the extensions on a list chosen by Microsoft, and the XSLT/XPath extension isn't on it yet - so, there, XSLT files have plain XML highlighting, with none of the extension's features. To run the extension in the Agents window, add this to your user settings:
"extensions.supportAgentsWindow": { "deltaxml.xslt-xpath": true }
The Agents window uses its own profile of extensions, so an extension you've disabled elsewhere - such as Red Hat's XML extension - may be enabled there. See AI Assistants.
Emmet Snippets
Emmet Snippets provide a convenient shorthand for inserting a number of literal result elements and attributes into your XSLT in one go. For example, entering:
ul>li.item$*2
provides the following output:
<ul>
<li class="item1"></li>
<li class="item2"></li>
</ul>
To enable Emmet snippets for XSLT, add the following setting:
"emmet.includeLanguages": {
"xslt": "xml"
}