Document names of AST node types for `syntax`

[verhovsky]

I opened https://zed.dev/schema/themes/v0.1.0.json to see what are all the syntax nodes that can be highlighted and it just says

                "syntax": {
                    "description": "The styles for syntax nodes.",
                    "default": {},
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/HighlightStyleContent"
                    }
                },

This definitions/HighlightStyleContent file is not linked anywhere in the docs.

[maxdeviant]

These are JSON schema links within the same document.

It links to this definition further up that describes the structure of HighlightStyleContent:

{
  "definitions": {
    "HighlightStyleContent": {
      "type": "object",
      "properties": {
        "color": {
          "default": null,
          "type": ["string", "null"]
        },
        "font_style": {
          "default": null,
          "anyOf": [
            {
              "$ref": "#/definitions/FontStyleContent"
            },
            {
              "type": "null"
            }
          ]
        },
        "font_weight": {
          "default": null,
          "anyOf": [
            {
              "enum": [100, 200, 300, 400, 500, 600, 700, 800, 900]
            },
            {
              "type": "null"
            }
          ]
        }
      }
    }
  }
}

[verhovsky]

Oh right. My issue is that there's no list in the schema or the docs of the AST node types like variable, constant, etc.

[verhovsky]

Having looked into this more, what would've helped me is that the syntax part on https://zed.dev/docs/extensions/themes should include an explanation that Zed uses tree sitter, that the grammars are in grammar.json and the highlight rules that group them into rules are in highlight.scm and the standard for what to name these things isn't well defined but a list can be seen in one.json and it also seems to be documented here https://github.com/zed-industries/zed/blob/6af5fdd1c27e887732e7857ba855432a57d20ced/docs/src/extensions/languages.md?plain=1#L91-L131 but saying "@title captures titles" isn't helpful. What is a title in Python or some other language?

I would also appreciate a way to quickly see what some text's node type is. Either a copy/paste-able command (I have to piece it together myself from reading the tree-sitter docs, right now I'm just guessing, turning nodes neon green and seeing if that text lights up green, it's tedious) or just showing it in the editor.

[probably-neb]

I recommend using the debug: open syntax tree view command in a buffer containing the language you wish to write queries for. You can click on nodes in the editor as well as the debug view and have their corresponding text/nodes highlighted in the other. You can also create a markdown file with code blocks for all of the languages you care about to quickly see what colors look like in many different languages in the same place :)