FreeMarker Formatter

A simple and lightweight VS Code extension for formatting FreeMarker templates.

Features

• Format entire FreeMarker documents
• Format selected text (intelligently skips empty lines to find proper indentation context)
• Support for mixed FreeMarker, HTML, CSS, and JavaScript
• Indent-only formatting: Preserves existing line breaks, only adjusts indentation
• Configurable indentation
• Smart indentation detection for range formatting (automatically detects brace context)

Usage

• Format Document: Shift+Alt+F (Windows/Linux) or Shift+Option+F (macOS)
• Format Selection: Select text and use Shift+Alt+F (Windows/Linux) or Shift+Option+F (macOS)

Note: This formatter uses indent-only mode. It only adjusts indentation and preserves all existing line breaks. See FORMATTING.md for details.

Configuration

• freemarker.formatter.indentSize: Number of spaces for indentation (default: 2)
• freemarker.formatter.useTabs: Use tabs instead of spaces (default: false)

Supported File Extensions

• .ftl
• .ftlh
• .ftlx

Development

Prerequisites

• Node.js (v14 or higher)
• Visual Studio Code

Setup

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode for development
npm run watch

Debugging

1. Open this project in VS Code
2. Press F5 to start debugging
3. A new VS Code window will open with the extension loaded
4. Open any .ftl file in the new window
5. Test formatting with Shift+Option+F (macOS) or Shift+Alt+F (Windows/Linux)

Running Tests

# Run all tests
npm test

# The test suite includes 12 comprehensive test cases covering:
# - HTML tag indentation
# - FreeMarker directive indentation
# - CSS code block formatting with brace awareness
# - JavaScript code block formatting with brace awareness
# - Mixed content formatting

Building and Installing

Build VSIX Package

# Install vsce (VS Code Extension Manager) if not already installed
npm install -g @vscode/vsce

# Package the extension
vsce package

# This will create a .vsix file (e.g., vscode-freemarker-formatter-0.0.1.vsix)

Install the Extension

Method 1: Install from VSIX file in VS Code

1. Open VS Code
2. Go to Extensions view (Cmd+Shift+X on macOS or Ctrl+Shift+X on Windows/Linux)
3. Click the ... menu at the top of the Extensions view
4. Select "Install from VSIX..."
5. Choose the .vsix file you built

Method 2: Install from command line

code --install-extension vscode-freemarker-formatter-0.0.1.vsix

Method 3: For development testing

Press F5 in VS Code to launch Extension Development Host without building a VSIX file.

Publishing to VS Code Marketplace

Prerequisites

1. Create a Visual Studio Marketplace publisher account
2. Get a Personal Access Token (PAT) from Azure DevOps
   • Organization Settings → Personal Access Tokens
   • Create new token with Marketplace (Manage) scope
   • Save the token securely

Update package.json

Before publishing, update the following fields in package.json:

{
  "publisher": "your-publisher-name",
  "version": "0.0.1",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/vscode-freemarker-formatter"
  }
}

Publish Steps

# Login to your publisher account (one-time setup)
vsce login your-publisher-name
# Enter your Personal Access Token when prompted

# Publish the extension
vsce publish

# Or publish with version bump
vsce publish patch    # 0.0.1 -> 0.0.2
vsce publish minor    # 0.0.1 -> 0.1.0
vsce publish major    # 0.0.1 -> 1.0.0

Verify Publication

After publishing, your extension will be available at:

https://marketplace.visualstudio.com/items?itemName=your-publisher-name.vscode-freemarker-formatter

Users can install it directly from VS Code Extensions view by searching for "FreeMarker Formatter".

Unpublish (if needed)

# Remove a specific version
vsce unpublish your-publisher-name.vscode-freemarker-formatter@0.0.1

# Remove entire extension (use with caution!)
vsce unpublish your-publisher-name.vscode-freemarker-formatter --force

License

MIT