Add tagged comment support

[anphir]

Another attempt to address Zed editor issue #11895 and Zed extensions issue #523 and provide highlighting and other features for comments containing defined tags.

Context

1. In March 2024 Zed editor pull request #9082 was rejected by @maxdeviant, concluding this functionality should be provided by an extension.

2. In June 2025 I opened Zed extension pull request #2865 in an attempt to provide such an extension.
   Because of the capabilities of current Zed extension API, this proposed extension is very limited.
   It only supports highlighting based on a fixed set of tags and assigned styles.
   Users would have to add these predefined styles manually to their local configuration.
   Language grammar developers would need to be convinced to add an injection query.

3. In July 2025 @notpeter commented my Zed extension pull request, wanting to think about whether this made sense to implement in core or whether the extension implementation is appropriate.
   Based on that I thought perhaps a new approach to adding the required functionality to Zed core might be accepted.

Features

• Users may opt-in to tagged comment support by creating a new JSON settings file.

• A new Zed action "open tagged comment configuration" opens the configuration file for editing, creating a default configuration if the file did not exist.

• Users may configure multiple groups of tags (NOTE, TODO, ...) and associated styles to use.

• Styles used in the default configuration are added to Zed themes.

• Users may configure which (parts of) tagged comments to include in outline views.

• tree-sitter-comment is used as grammar for tagged comments.

• The required highlighting and outline queries are created dynamically based on user configuration and updated on configuration change.

• Required injection queries are added dynamically to supported languages when these languages are loaded by Zed.

• Both languages built into Zed and provided as an extension may be supported.

• Languages are supported by adding - usually small - definitions in Zed source.

• Unless I missed some, all languages built into Zed or provided by an extension shipped with Zed are already supported.

• A few languages from Zed extensions are already supported too.

• Language (extension) developers may still include injections for tagged comments in their injections file.
  Eventually already existing definitions in Zed should be removed in that case.

• Users may opt-out again from tagged comment support by removing the configuration file or deleting the contained definitions.

Potential Additions and Improvements

• Improved search for tagged comments.
  Currently only the existing text search can be used.
  This works well when searching for a single tag, but could be more comfortable when searching for multiple tags.
  An enhanced UI probably makes sense.
  The text based search also shows false positives, e.g. when a configured tag is part of a string literal.
  I experimented with tree-sitter query based search using functions already existing in Zed.
  It worked well for the current file but needs more thinking for project wide search.

• Some UI for quickly filtering the comments shown in outline views might be helpful.

• UI for configuration as alternative to editing the configuration file.

• Support for still missing languages from Zed extensions.

• Description in Zed's documentation.

[anphir]

I understand concerns about having to maintain queries for all existing and future language extensions. I wasn't enthusiastic when looking into tree-sitter grammars of languages I am unlikely to ever use.

At the moment there is only one reliable alternative approach I can think of:

• The required injection query is added to the languages' "injections.scm" themselves.
  If the basic tagged comment support is merged into Zed, language extension maintainers might by motivated to do so or accept pull request.
  This would need to be done for language extensions shipped with Zed and languages built into Zed too.
• Implement a mechanism allowing users to extend/override injection queries for specific languages.
  This would enable users to work around problems with languages not (yet) implementing the required injection query.
  Eventually such a mechanism could also be used for purposes other than tagged comment support.
  Extensions might be allowed to provide queries to be added for other languages (e.g. Leptos extension for Rust).
  A solution I have frequently seen is a set of configuration directories with files containing configuration snippets being added from diverse origins.

When I started to work on support for tagged comments I was also thinking about deriving the injection query from the language's grammar or highlighting queries for comments.
Given the large diversity of languages and node names used, I still doubt this can be done reliably.

[anphir]

Hi @maxdeviant, to address your concerns I did the following:

• Removed the runtime creation of injection queries for tagged comments (the thing you did not like).
• Added the injection query required for tagged comments to "injections.scm" for all languages built into Zed and language extensions shipped with Zed (unless I missed some).
• Implemented a mechanism to allow users to configure additional injection queries.
  Users may create a single configuration file containing injection queries for each language.
  To e.g. add some injection queries for TOML that file would be at "user-config-dir/injections/toml.scm".
  This mechanism is intended as a workaround for Zed language extensions not (yet) supporting tagged comments, but might be useful for other purposes too.

[umbrageodotus]

Could support for #12518 be implemented here too? As rust-analyzer, for example, has it's own folding mechanism.

[anphir]

Could support for #12518 be implemented here too? As rust-analyzer, for example, has it's own folding mechanism.

I haven't looked into how Zed implements code folding, so I don't know if injections would be needed and how it relates to comment highlighting.
As code folding and syntax highlighting are different features, its probably better to have separate pull requests for changes.

[umbrageodotus]

Zed DOESN'T implement region-based code folding, afaik.

[maxdeviant]

Thank you for the PR.

Now that we have the comment extension available I think that is the direction we should continue to pursue.

It seems that the remaining work is to make sure that the various languages support the comment language injection, like what has been done here: #39714.