YAML Navigator

Navigate your custom YAML files with Ctrl+Click go-to-definition and hover tooltips — for both local variable definitions and functions imported from external YAML files.

Features

Hover tooltip — hover over any variable or function name to see its full definition block inline
Go-to-Definition — Ctrl+Click a variable name to jump to where it's defined in the same file
Cross-file navigation — Ctrl+Click an imported function name to open the source file at the exact definition line
Multiple variable kinds — configure distinct labels (e.g. Parameter, Loop Parameter) for the same prefix depending on context
Fully config-driven — nothing is hardcoded; the extension only activates the features you configure in settings.json

Requirements

VS Code 1.75.0 or higher
Cursor (any recent version — uses the same extension API)

Configuration

All settings live under the yamlNavigator namespace in your settings.json. Open it with Ctrl+Shift+P → Preferences: Open User Settings (JSON) or place them in .vscode/settings.json for per-project configuration.

`yamlNavigator.variableKinds`

An array of objects defining which YAML lines declare a variable and what label to show in the tooltip.

Property	Type	Required	Description
`prefix`	string	✅	Text that precedes the variable name on the declaration line (e.g. `- key:`)
`label`	string	✅	Label shown in the hover tooltip (e.g. `Parameter`, `Loop Parameter`)
`parentKey`	string	❌	Only match this kind when an ancestor line at a lower indent level contains this key

Example:

"yamlNavigator.variableKinds": [
  { "prefix": "- key:", "label": "Parameter" },
  { "prefix": "- key:", "label": "Loop Parameter", "parentKey": "$loopItems" }
]

When two entries share the same prefix, the one with a matching parentKey takes priority. The generic entry (no parentKey) is the fallback.

`yamlNavigator.functionImportPrefix`

The string that precedes the list of imported function names.

"yamlNavigator.functionImportPrefix": "- Functions:"

`yamlNavigator.functionSourcePrefix`

The string that precedes the path to the source file containing the function definitions.

"yamlNavigator.functionSourcePrefix": "Source:"

`yamlNavigator.sourceRoot`

Optional. A subfolder within the workspace root used as an additional path resolution fallback. Rarely needed — the extension automatically tries several path strategies.

"yamlNavigator.sourceRoot": "src"

Full Example

Project structure

project/
└── src/
    ├── vehicle-classification.yaml
    └── functions/
        └── vehicle-functions.yaml

`settings.json`

{
  "yamlNavigator.variableKinds": [
    { "prefix": "- key:", "label": "Parameter" },
    {
      "prefix": "- key:",
      "label": "Loop Parameter",
      "parentKey": "$loopItems"
    }
  ],
  "yamlNavigator.functionImportPrefix": "- Functions:",
  "yamlNavigator.functionSourcePrefix": "Source:"
}

`src/vehicle-classification.yaml`

Imports:
  - Functions: classifyDrivetrain, resolveEmissionStandard
    Source: "src/functions/vehicle-functions.yaml"

VehicleClassification:
  Parameters:
    - key: BodyStyle
      $type: string
      $definition: Vehicle.roofType == "retractable" ? "Convertible" : "Sedan"
    - key: DrivetrainType
      $type: string
      $definition: classifyDrivetrain(Vehicle.axleConfig, Vehicle.transferCase)
    - key: EmissionClass
      $type: string
      $definition: resolveEmissionStandard(Vehicle.exhaustProfile, Vehicle.modelYear)
    - key: IsElectric
      $type: boolean
      $definition: Vehicle.fuelType == "BEV" || Vehicle.fuelType == "PHEV"
    perVariant:
      $loopItems:
        - key: VariantLabel
          $type: string
          $definition: Vehicle.trimLevel + " " + Vehicle.modelYear

RegistrationDetails:
  CountryCode: PL
  BodyStyle: BodyStyle
  DrivetrainType: DrivetrainType
  EmissionClass: EmissionClass
  IsElectric: IsElectric

`src/functions/vehicle-functions.yaml`

classifyDrivetrain(AxleConfig, TransferCase):
  $input: [string, string]
  $output: string
  $definition: >
    AxleConfig == "4x4" && TransferCase == "active"
      ? "AWD"
      : AxleConfig == "4x4"
        ? "4WD"
        : AxleConfig == "rear"
          ? "RWD"
          : "FWD"

resolveEmissionStandard(ExhaustProfile, ModelYear):
  $input: [string, number]
  $output: string
  $definition: >
    ModelYear >= 2025
      ? "Euro 7"
      : ExhaustProfile == "low-nox"
        ? "Euro 6d"
        : "Euro 6"

What you get

Action	Result
Hover over `BodyStyle` anywhere in the file	Tooltip: Parameter: `BodyStyle` with its full definition block
Hover over `VariantLabel`	Tooltip: Loop Parameter: `VariantLabel`
Hover over `classifyDrivetrain`	Tooltip: Function: `classifyDrivetrain` with its block, sourced from `vehicle-functions.yaml`
`Ctrl+Click` `EmissionClass`	Jumps to the `- key: EmissionClass` line in the same file
`Ctrl+Click` `resolveEmissionStandard`	Opens `vehicle-functions.yaml` at the `resolveEmissionStandard` definition line

How path resolution works

When a Source: value like "src/functions/vehicle-functions.yaml" is encountered, the extension tries the following candidates in order and uses the first path that exists on disk:

Strip the leading path segment if it matches the name of the folder containing the current file — handles the common case where the Source: path includes the current folder name
Resolve relative to the current file's directory
Resolve from the workspace root
Resolve from workspace root + yamlNavigator.sourceRoot

This means Source: "src/functions/vehicle-functions.yaml" works correctly whether your workspace root is the project root or the src/ folder itself.

Tips

Settings take effect immediately — no restart needed after changing settings.json
Both hover and Ctrl+Click work anywhere the variable name appears, not just at its declaration (e.g. when it's referenced as a value in another field)
If a function's source file can't be found, hover and Ctrl+Click silently do nothing — check the Source: path and your workspace root
The extension activates only for YAML files (.yaml, .yml)

YAML Navigator Aligator

Dawid Nowakowski