Back in 2022 I announced a new Q# community project - a proper, standalone TextMate grammar for Q#, built with a real build pipeline, test suite and multiple output formats, rather than the handful of regular expressions that the QDK extension shipped with at the time. It has quietly lived in the qsharp-community organization ever since.
Today I’m happy to report that the grammar has “graduated” - a snapshot of it is now officially vendored into the QDK extension itself, replacing the original hand-written grammar the extension used to ship with, and it already shipped in v1.31.
From a side project to an official dependency π
The approach here mirrors something that happened years ago with the C# extension for VS Code, where the TextMate grammar also lives in its own external repo, with its own tests and build process, and periodic snapshots of it get vendored into the main extension. The grammar itself isn’t moving in-house - it stays community owned and developed in qsharp-community/qsharp-tmLanguage, exactly like the C# grammar does in its own repo. I have been maintaining the Q# grammar the same way from the start, and it was always the plan to eventually get a snapshot of it vendored into the extension proper, replacing the original, much more limited hand-written grammar - I actually remember discussing this with the original QDK team members years ago.
What finally made this possible now is that the qsharp-community/qsharp-tmLanguage repo recently went through a serious modernization effort, bringing it up to date with modern Q# syntax and full compatibility with QDK/Q# 1.x. You can see the scope of that work in the list of merged pull requests - it touched pretty much every corner of the grammar.
Landing in the QDK extension π
With the grammar modernized, I put together a PR that imports it straight into the QDK extension, following the same vendoring approach mentioned above. The difference in highlighting quality compared to the old, basic grammar is immediately obvious on pretty much any non-trivial Q# file - operations, functors, newer syntax constructs, and various literals are now all tokenized properly instead of falling back to plain text.
The PR was reviewed and merged by the QDK team, and the updated grammar is already shipping as part of the extension starting with v1.31. If you have the QDK extension installed and up to date, you are already benefiting from this - no additional configuration is required.
A bonus: better Q# highlighting on github.com too π
There is a nice side effect to this change. github.com doesn’t maintain its own bespoke syntax highlighting for every language - it sources its grammars via github-linguist, and for Q# that grammar is pulled directly from the QDK repo. Since the QDK now ships the modernized community grammar, this same grammar will eventually become the official Q# syntax highlighting on github.com as well.
The linguist project only refreshes its bundled grammars on a quarterly cadence, so this particular improvement won’t show up on github.com immediately - but it should land with their next refresh, expected in September.
Final thoughts π
It’s great to see a community side project make its way into the official tooling, and to have a hand in improving the day to day experience of writing Q# - both in the editor and, soon, on github.com. The grammar keeps living and evolving in the community repo, with the QDK extension picking up new snapshots over time, so if you spot any tokenization issues, please do report them (or send a PR) on the qsharp-community/qsharp-tmLanguage repo.
