VSCode Integration

Integrate maplibre-yaml validation into your VSCode workflow for real-time error detection and quick fixes.

Quick Start (No Extension Required)

You can use maplibre-yaml with VSCode immediately using the built-in Tasks feature:

Step 1: Add Task Configuration

Create or update .vscode/tasks.json in your project:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "maplibre-yaml: Validate Current File",
      "type": "shell",
      "command": "npx",
      "args": [
        "@maplibre-yaml/cli",
        "validate",
        "${file}",
        "--format",
        "vscode"
      ],
      "problemMatcher": {
        "owner": "maplibre-yaml",
        "fileLocation": "absolute",
        "pattern": {
          "regexp": "^(.+):(\\d+):(\\d+): (error|warning): (.*)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5
        }
      },
      "presentation": {
        "reveal": "silent",
        "panel": "shared"
      },
      "group": "build"
    }
  ]
}

Step 2: Run the Task

Open a .yaml file
Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
Type “Run Task”
Select maplibre-yaml: Validate Current File

Step 3: View Errors

Errors appear in the Problems panel (Cmd+Shift+M / Ctrl+Shift+M) with:

✅ Clickable file paths
✅ Line and column numbers
✅ Error messages with context
✅ Quick navigation to error locations

Configuration Files

Complete tasks.json

Download the complete configuration with all tasks: tasks.json example

Includes:

Validate Current File: Validates the open file
Validate All Configs: Validates all YAML files
Watch and Validate: Continuous validation

YAML Schema Settings

Add to .vscode/settings.json for autocomplete:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/design-practices/maplibre-yaml/main/schemas/map-block.json": [
      "configs/**/*.yaml",
      "*.map.yaml"
    ]
  },
  "files.associations": {
    "*.map.yaml": "yaml",
    "**/configs/**/*.yaml": "yaml"
  }
}

Download complete settings.json

Usage Examples

Validate on Save

Set up a keyboard shortcut:

Press Cmd+K Cmd+S (Mac) or Ctrl+K Ctrl+S (Windows/Linux)
Search for “Run Task”
Add keybinding (e.g., Cmd+Shift+V)
Configure to run maplibre-yaml: Validate Current File

Batch Validation

Run maplibre-yaml: Validate All Configs to validate all files in your project.

Output appears in the Problems panel grouped by file.

Watch Mode

Run maplibre-yaml: Watch and Validate for continuous validation:

Runs in background
Updates Problems panel on file save
Shows real-time errors
Perfect for development workflow

Problem Matcher

The VSCode Problem Matcher parses CLI output in the format:

file:line:column: severity: [path] message

Example:

/Users/you/project/config.yaml:5:10: error: [config.center] Expected array, got string

This enables VSCode to:

Parse error locations
Underline errors in the editor
Display in Problems panel
Provide quick navigation

Output Format

The --format vscode flag produces Problem Matcher-compatible output:

maplibre-yaml validate config.yaml --format vscode

Output:

/path/to/config.yaml:5:10: error: [config.center] Expected array
/path/to/config.yaml:12:3: warning: [layers[0]] Deprecated property

Keyboard Shortcuts

Recommended shortcuts:

Action	Default	Suggested
Run Task	`Cmd+Shift+P` > “Run Task”	`Cmd+Shift+V`
Problems Panel	`Cmd+Shift+M`	-
Next Error	`F8`	-
Previous Error	`Shift+F8`	-

Future: Native Extension

We’re planning a native VSCode extension with:

✅ Real-time validation as you type
✅ Autocomplete for map properties
✅ Hover documentation
✅ Inline map preview
✅ Go to definition for layer references
✅ Rename refactoring

Roadmap: Extension Architecture

Phase 1 (Available Now): CLI with Tasks Phase 2 (Q1 2025): Extension MVP Phase 3 (Q2 2025): Language Server Phase 4 (Q3 2025): Preview Webview

Troubleshooting

Errors Don’t Appear in Problems Panel

Check that the task includes problemMatcher
Verify --format vscode is in the args
Ensure file paths are absolute
Check Problems panel filter settings

Task Not Found

Ensure .vscode/tasks.json exists in project root
Reload VSCode window
Check JSON syntax is valid

Permission Errors

On first run, VSCode may ask to allow task execution. Click “Allow” to proceed.