Liquid Template Debugger for VS Code

A powerful VS Code extension for debugging and developing DotLiquid templates with real-time variable inspection, step-by-step execution, and format transformations.

Features

🔍 Step-by-Step Debugging

• Execute templates line by line
• Set breakpoints with optional conditions
• Step into, over, and out of template blocks
• Continue execution to next breakpoint

📊 Variable Inspection

• View all variables and their current values
• Track data origin and transformations
• Inspect nested objects and arrays
• Watch specific expressions

🔄 Format Transformations

Support for multiple data formats:

• JSON - Standard web data format
• XML - Enterprise and legacy systems
• CSV - Spreadsheet and tabular data
• Text - Key-value pairs and custom formats

Convert between any supported formats seamlessly.

🎯 Rich Language Support

• Syntax highlighting for Liquid templates
• Auto-completion for Liquid tags and filters
• Bracket matching and auto-closing
• Code folding for control structures

🛠️ Developer Tools

• Beautify JSON and XML
• Validate output format
• Load sample templates
• Transform data formats

Requirements

• VS Code 1.80.0 or higher
• .NET 9 SDK or higher (for running the debugger service)

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Liquid Template Debugger"
4. Click Install

From VSIX File

1. Download the .vsix file
2. Open VS Code
3. Go to Extensions
4. Click "..." menu → "Install from VSIX..."
5. Select the downloaded file

Quick Start

1. Open a Liquid Template

Create or open a .liquid file in VS Code. The extension will automatically activate.

2. Start Debugging

Press Ctrl+Shift+L (or Cmd+Shift+L on Mac) to open the debugger panel, or use the command palette:

• Press F1 or Ctrl+Shift+P
• Type "Liquid: Open Debugger Panel"

3. Load Template and Data

In the debugger panel:

• Load your template and data files
• Or click "Load Sample" to try a demo

4. Debug

• Click "Step" to execute line by line
• Set breakpoints by clicking line numbers
• Inspect variables in the Variables panel
• Watch the output build in real-time

Usage

Commands

Access these commands via Command Palette (F1 or Ctrl+Shift+P):

• Liquid: Start Debugger - Start the debugger service
• Liquid: Stop Debugger - Stop the debugger service
• Liquid: Open Debugger Panel - Open the debugger UI
• Liquid: Load Sample Template - Load a sample template
• Liquid: Beautify JSON - Format JSON in active editor
• Liquid: Beautify XML - Format XML in active editor
• Liquid: Transform Data Format - Convert between formats

Keyboard Shortcuts

• Ctrl+Shift+L / Cmd+Shift+L - Open Debugger Panel

Debug Configuration

Create a .vscode/launch.json file in your workspace:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "liquid",
            "request": "launch",
            "name": "Debug Liquid Template",
            "template": "${file}",
            "data": "${workspaceFolder}/data.json",
            "format": "json"
        }
    ]
}

Then press F5 to start debugging with your configuration.

Extension Settings

Configure the extension via VS Code settings:

• liquidDebugger.port - Port for the debugger service (default: 5050)
• liquidDebugger.autoStart - Auto-start service when opening .liquid files (default: true)
• liquidDebugger.dotnetPath - Path to .NET runtime (default: "dotnet")
• liquidDebugger.servicePath - Custom path to debugger service DLL (optional)

Examples

Basic Template Debugging

Template (order.liquid):

{% assign total = 0 %}
{% for item in items %}
  Item: {{ item.name }} - ${{ item.price }}
  {% assign total = total | plus: item.price %}
{% endfor %}
Total: ${{ total }}

Data (order.json):

{
  "items": [
    { "name": "Widget", "price": 10.99 },
    { "name": "Gadget", "price": 25.50 }
  ]
}

Format Transformation

Transform XML to JSON:

1. Open XML file
2. Run "Liquid: Transform Data Format"
3. Select input format: XML
4. Select output format: JSON

Troubleshooting

Service Won't Start

• Ensure .NET 9 SDK is installed: dotnet --version
• Check if port 5050 is available
• Try changing the port in settings

Extension Not Activating

• Ensure file has .liquid extension
• Try manually starting: "Liquid: Start Debugger"

Breakpoints Not Working

• Ensure template is loaded in debugger
• Check breakpoint conditions are valid
• Verify line numbers match template

Architecture

The extension consists of two parts:

1. VS Code Extension (TypeScript)

   • Provides UI and commands
   • Manages debugger service lifecycle
   • Integrates with VS Code debugging protocol

2. Debugger Service (C# / .NET)

   • ASP.NET Core web service
   • Executes and debugs Liquid templates
   • Provides REST API for debugging operations

Contributing

Contributions are welcome! Please see the GitHub repository for:

• Source code
• Issue tracking
• Development guidelines

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Documentation: Full Documentation

Release Notes

1.0.0

• Initial release
• Step-by-step debugging
• Variable inspection
• Format transformations
• Syntax highlighting
• Breakpoints and watches

Enjoy debugging your Liquid templates! 🚀