make VS Code parse and display the structure of a new language to the outline region of VSC

Question

I'm trying to make VSC display the structure of a document containing a DSL (domain specific language) by adding the language definition to VSC. The structure should appear in VSC "outline view" where all document structure is shown for installed languages (like json, markdown, html, etc.)

The DSL is quite simple and just some elements in capital letters should appear in the outline and remain the hierarchy:

WORD xxx
GRAMMAR xxx
STRUCTURE xxx xxx
     xxx xxx xxx xxx
MEANING xxx xxx xxx 
    SUB_MEANING xxx xxx xxx xxx
        SUB_SUB_MEANING xxx xxx xxx

I followed all hints on stackoverflow that all lead to official documentations of VSC and/or the language server protocol (LSP). However, none helped, not at all -.- Yes, I could use the CodeMap extension, but I don't want to be dependent on that since VSC actually is able to understand new languages. For well known languages, there is no need for creating a dedicated tree view element or something elses, so there MUST be a way to make VSC parse the language structure.

"outline view" in VSC remains empty. I figured out that the installed language support for (e.g.) markdown or json does also not produce any content to "Outline" if one deletes the folder "xxx-language-features" (xxx stands for the language) within the extension folder of VSC. So it seems that I need a language-feature-extension, too.

I went through https://code.visualstudio.com/api/language-extensions/language-configuration-guide and https://microsoft.github.io/language-server-protocol/ and many other stuff including the LSP-example from the Github-Repo of VSC but there is NOTHING that helps on that. I also tried to create a new language by aid of "yo code". Nothing. The LSP-example provided by Microsoft is for plaintext files...how useful is it to create a language server for plaintext?! I would like to have an example on a language. Looking at the compiled files inside extensions doesn't help since they're minified.

There is no complete "how to" on that issue - So, any help is appreciated! How can I tell VSC to parse the document structure into the "outline view"?

Answer 1

I searched the wrong places for a solution and maybe missed the forest for the trees after some wasted days. A colleague then had a virgin look at the problem and he came up with the solution below after some hours. Basically, DocumentSymbolProvider is what one needs.

Searching for this keyword then provides some examples, e.g. here. The official docs however provide nothing except the information that you can create an instance, whereas the important code about HOW TO USE IT is represented by .... WOW - that's what I call a doc -.-

Still there are some things unclear but at least we can now work with that base:

class MLWDocumentSymbolProvider implements vscode.DocumentSymbolProvider {
public provideDocumentSymbols(document: vscode.TextDocument,
        token: vscode.CancellationToken): Thenable<vscode.SymbolInformation[]> {
    return new Promise((resolve, reject) => {

      // that's the important variable. It must be a multidimensional array, one dimension for each level you need to display.
      let symbols = [];

      let icon_main = vscode.SymbolKind.Class;
      let icon_second = vscode.SymbolKind.Field;
      let icon_third = vscode.SymbolKind.String;

      // check each line of the document about your keywords
      for (let i = 0; i < document.lineCount; i++) {
        let line = document.lineAt(i);
        if(line.text.trim().startsWith("WORD")) {
          symbols.push(new vscode.DocumentSymbol("Level 1: WORD", document.lineAt(i+1).text.trim(), icon_main, line.range, line.range ));
        } /* elses for the levels below */
       }

      resolve(symbols);
        });
    }

}

I guess Gamma11's answer was close, somehow. Owed to the lack of information in the official docs about where and how to use it, it unfortunatelly couldn't really help us.

Gaining knowledge about VSC-coding seems to be very hard due to the fact that the docs don't provide much information except the base structure. If someone knows a site with complete examples or descriptions about the classes/interfaces/functions, please leave a comment. In almost 20 years of coding I have never seen such a lack of documentation of such a huge project, where the main parts are represented by ... or there is simply nothing at all about an object -.-