Allow extensions to override grammar query files

[ck37]

Problem

Zed extensions cannot override tree-sitter grammar query files, forcing grammar maintainers to choose between supporting Zed or other editors like Neovim, which contradicts tree-sitter's goal of unified grammar definitions.

Current Behavior

When an extension specifies a grammar via repository + rev in extension.toml:

1. Zed clones the grammar repository
2. Zed loads queries only from the cloned grammar's queries/ directory
3. Zed completely ignores any query files the extension provides in languages/LANG/*.scm

This means extensions cannot provide editor-specific customizations, even though the extension API suggests they should be able to.

Expected Behavior

Extensions should be able to provide override query files that take precedence over the grammar's defaults.

For example, if an extension provides languages/quarto/highlights.scm, Zed should load that file instead of the grammar's queries/highlights.scm.

Precedence order should be:

1. Extension-provided queries (languages/quarto/*.scm)
2. Grammar-provided queries (queries/*.scm)
3. Grammar-provided editor-specific queries (queries/zed/*.scm)

Real-World Impact

This limitation has concrete consequences:

1. Grammar fragmentation: Grammar authors must create editor-specific forks or branches, defeating the purpose of tree-sitter as a unified parsing solution.

2. Scope incompatibility: Zed themes use legacy scope names (@text.title, @emphasis.strong) while nvim-treesitter uses modern conventions (@markup.heading, @markup.bold). Without extension overrides, grammars must choose one editor to support well.

3. Maintenance burden: Query files must be duplicated across grammar repositories and extension repositories, as noted in discussion ❓ Why does Zed encourage fragmentation of Tree Sitter queries between editors? #16860.

4. Tree-sitter design contradiction: Tree-sitter documentation states "all files needed to highlight a given language are normally included in the same git repository as the Tree-sitter grammar," yet Zed's current architecture encourages the opposite.

Example Case

The zed-quarto-extension needs to use tree-sitter-quarto but cannot because:

• tree-sitter-quarto uses nvim-treesitter scopes (@markup.*) in its default queries/highlights.scm
• Zed themes only recognize legacy scopes (@text.*, @emphasis.strong)
• The extension provides Zed-compatible queries in languages/quarto/highlights.scm
• Zed ignores the extension's queries and loads the grammar's incompatible queries
• Result: No syntax highlighting in Zed

Workaround: Fork the grammar or maintain a separate branch with Zed-specific queries, creating exactly the fragmentation tree-sitter was designed to prevent.

Precedent from Other Editors

• Neovim: Extensions/plugins can override grammar queries using runtime paths
• VSCode: Language extensions can provide custom TextMate grammars
• Helix: Query override via configuration is supported

Related

• Discussion ❓ Why does Zed encourage fragmentation of Tree Sitter queries between editors? #16860: "Why does Zed encourage fragmentation of Tree Sitter queries between editors?"
• This discussion has been unanswered since it was posted

Implementation Notes

One approach could be to check for query files in this order:

1. Extension's languages/LANG/highlights.scm
2. Grammar's queries/highlights.scm
3. Fall back to grammar's queries/zed/highlights.scm if present

This would allow extensions to provide editor-specific customizations while still using upstream grammars, maintaining the tree-sitter philosophy of grammar reuse across editors.

[MrSubidubi]

We would much rather have you write issues yourself than prompt an LLM to do the job for you, which adds a lot of words for no actual actionable content. Additionally, you completely ignored the issue form, which we require for good reasons.

Lastly, what you request here is already exactly the case - we pick the queries from the extension and never from the grammar.

This is the second time you report something as broken/try fixing something which works exactly the way you want it to work. This is a waste of everyones time, including yours. Next time, please take the time to recheck before reporting. Thanks

[ck37]

@MrSubidubi Is there a file, document, or extension you can refer to that supports this? I have indeed been struggling for many hours and for now I've just changed the grammar to provide old Zed scopes.

[ck37]

All I'm trying to do is add syntax highlighting for Quarto to Zed, for free. Or if you have any reaction to #16860 that would be helpful.

[MrSubidubi]

Thanks for answering in person, appreciate it.

Is there a file, document, or extension you can refer to that supports this?

zed/crates/extension_host/src/extension_host.rs

Lines 1278 to 1291 in ce20e71

	let mut language_path = self.installed_dir.clone();
	language_path.extend([
	Path::new(language.extension.as_ref()),
	language.path.as_path(),
	]);
	self.proxy.register_language(
	language_name.clone(),
	language.grammar.clone(),
	language.matcher.clone(),
	language.hidden,
	Arc::new(move || {
	let config = std::fs::read_to_string(language_path.join("config.toml"))?;
	let config: LanguageConfig = ::toml::from_str(&config)?;
	let queries = load_plugin_queries(&language_path);

If you use zed: open log you will see the issue you are running into. I suspect that we are unable to compile the old higlights query against the updated grammar, so no highlighting is possible.

I still would recommend you to the Discord where you can ask questions regarding this. You will get answers there and can still open an issue after should you run into one.

[ck37]

Thank you, I will study that and try to understand how to resolve what I'm facing. I'll get on Discord too.