Adding simple features to yaml (ctrl-click references) - best method?


I have custom data files for a project that are in yaml format, the yaml basically being an easy framework to hold lists of strings used in the project. I've basically developed my own language for parsing that text, and over time it's gotten very complicated, to the point that I needed to add functionality to it. Using the LivePlugins plugin, I wrote a plugin that allows for custom completion of certain things when I'm entering the string literals. Big learning curve, but works great now.

Now, I'd like to add the ability to ctrl-click on some elements and be brought to their source in whatever other yaml file they are in. Here's some example yaml:

- Yep
- Absolutely
- Yes
- Sounds good
- Can I do it? [yes]!
- I do believe so. [yes].
- [yes], not a problem.

In short, it randomly generates responses for an ai chatbot. How the format works is when can_i_do_it is used, one of the responses is picked at random. When a [response] appears in one of the string literals, at runtime it is parsed, and a random element from that list is inserted. So for example, returning a can_i_do_it response could come up with "Sounds good, not a problem." Sorry if that explanation is unnecessary, I do better with context myself, so, lots of detals.

Anyway - so my yaml files have gotten massive. I've well over 1400 lines of dialogue, with deeply intertwined references, as well as more than just [] replacements, spread over 5 or so files. I'd begun forgetting different response options and started duplicating them, hence the auto-completion. Godsend.

But now, even though I can type something in and get autocomplete suggestions, I'd like the ability to ctrl-click on [obscure_response] and be taken to that yaml entry in whatever file. Navigating to the response, I've got handled. I just don't know how to implement the ctrl-click.

I've looked at some of the stuff for the SimpleLanguage example, and that is excessively complicated. I'm not writing a new language. I'd just like to add something to yaml.

Is it possible to do this by just extending/overriding some of the yaml classes and have the functionality just work? Or make a new yaml plugin that is just the existing one extended?

The documentation on plugin development is all over the map. Some is barely informative, most is way out of date, and the rest assume you've been writing IDEA plugins for years and have the whole system down pat.

Any examples or tips would be much appreceiated.


The way i see it (i'm no expert, only junior also struggling with an IDEA plugin) you need at least two things.
Patterns, to indicate intellij when it should look for a reference. In your case, it should be simple enough.
And a class that extends PsiReference.
That would be the least easy part i think. I had to work with reference for a custom language ahd used the dom model for references in xml files.
I don't know how the YAML works.

if you want, you can take a look at how i did it (i don't know if i complied to good practices tho) in package fr.nereide.reference

Hope this helps



Thanks for the answer, Gaëtan.

I would just add that you should provide references for YAML string literals, with the text range covering the reference parts. These references should resolve to the YAML keys you should find in your definition files.

Please refer to the docs:

You can also take a look at example implementations on


Please sign in to leave a comment.