HAML Hero

Comprehensive HAML support for Visual Studio Code with advanced syntax highlighting, linting, and auto-formatting capabilities.

Features

• 🎨 Enhanced Syntax Highlighting: Comprehensive syntax highlighting for all HAML features, including multi-line ruby and hash attributes
• ✨ Auto-Formatting: Format HAML files on save (powered by haml-lint)
• 🔍 Real-time Diagnostics: Live linting feedback with warnings and errors as you type (powered by haml-lint)
• ⚙️ Highly Configurable: Customize linter path, formatter mode, and additional arguments

Requirements

For auto-formatting and linting, you need to install haml-lint:

Project-Level Installation (Recommended)

Add to your Gemfile:

group :development do
  gem 'haml_lint', require: false
end

Then run:

bundle install

Global Installation

gem install haml_lint

Warning: A global installation will be pinned to a specific version of Ruby that may not match your project

VS Code Settings

Auto-formatting is enabled under default vscode settings, but if you have another linter installed (like Prettier) you may need to add these settings to your settings.json file to enable HAML formatting.

{
  "[haml]": {
    "editor.defaultFormatter": "XanderDoom.haml-hero",
    "editor.formatOnSave": true,
    "editor.formatOnPaste": true
  }
}

Extension Settings

This extension has the following settings:

Core Settings

• hamlHero.enableFormatting: Enable automatic formatting with haml-lint (default: true)
• hamlHero.enableAutocorrections: Enable additional auto-formatting rules that complement haml-lint's (default: true)
• hamlHero.enableDiagnostics: Enable real-time linting diagnostics (default: true)

Linter Configuration

• hamlHero.linterPath: Full path to the haml-lint executable (default: "haml-lint")
  • For global installation: leave as "haml-lint"
  • For Bundler: use "bundle exec haml-lint" or full path to bundle
• hamlHero.configPath: Path to a custom .haml-lint.yml config file
  • If not specified, checks workspace root for .haml-lint.yml
  • If no config file is found, haml-lint uses its built-in defaults
  • Supports ~ for home directory and relative paths from workspace root
  • Example: "~/.haml-lint.yml" or "config/.haml-lint.yml"
• hamlHero.additionalLinterArguments: Additional arguments to pass to haml-lint when running diagnostics (default: "")
• hamlHero.globallyDisabledLinters: List of haml-lint rules to disable globally across all projects (default: [])
  • Rules are excluded using haml-lint's --exclude-linter flag
  • Applies to both diagnostics and formatting
  • Overrides local workspace .haml-lint
  • Use the Quick Fix menu on any diagnostic to add rules here
  • Example: ["IdNames", "LineLength", "ClassesBeforeIds"]
• hamlHero.disabledRubocopRules: List of RuboCop cops to disable globally when linting Ruby code in HAML templates (default: [])
  • Cop names should be in format Namespace/CopName (e.g., Style/StringLiterals, Lint/EmptyLine)
  • Use the Quick Fix menu on any RuboCop diagnostic to add rules here
  • These are merged with project-level .rubocop.yml settings
  • Example: ["Style/SingleQuotedStrings", "Metrics/LineLength"]

Formatter Settings

• hamlHero.enableFormatting: Enable/disable automatic formatting with haml-lint (default: true)
• hamlHero.enableAutocorrections: Enable/disable built-in autocorrections for TrailingWhitespace, FinalNewline, and SpaceInsideHashAttributes (default: true)
  • These corrections are applied after haml-lint's formatting
  • Disable if you only want haml-lint's auto-corrections
• hamlHero.formatterMode: Determines which rubocop auto-corrections to apply (default: "safe")
  • "safe": Only apply safe auto-corrections (--auto-correct)
  • "all": Apply all auto-corrections, including potentially unsafe ones (--auto-correct-all)
  • This only applies to formatting Ruby blocks, not to the HAML itself
  • See Rubocop: Autocorrect for more information
• hamlHero.formatInBackground: When enabled, files save immediately and formatting runs in the background (default: true)
  • Provides a more responsive experience
  • Set to false if you prefer blocking formatting before save completes
• hamlHero.additionalFormatterArguments: Additional arguments to pass to haml-lint when formatting (default: "")

Built-in Autocorrections

In addition to haml-lint's auto-corrections, HAML Hero applies several automatic corrections that haml-lint cannot handle:

• TrailingWhitespace: Removes trailing spaces and tabs from all lines
• FinalNewline: Ensures files end with exactly one newline (or no newline if configured as present: false in .haml-lint.yml)
• SpaceInsideHashAttributes: Normalizes spacing in hash attributes based on your configuration
  • space style (default): %tag{ key: value }
  • no_space style: %tag{key: value}
  • Reads configuration from the SpaceInsideHashAttributes linter settings in .haml-lint.yml

These corrections run automatically after haml-lint's formatting and are included in both sync and background formatting modes.

Example Configuration

{
  "hamlHero.linterPath": "bundle exec haml-lint",
  "hamlHero.formatterMode": "all",
  "hamlHero.configPath": "config/.haml-lint.yml",
  "hamlHero.additionalFormatterArguments": "--parallel"
}

Configuring haml-lint Rules

Option 1: Use workspace config (recommended for team projects)
Create .haml-lint.yml in your project root. This will automatically be used.

Option 2: Use custom config location
Set hamlHero.configPath to point to your config file. This can be configured per-workspace, so if you don't want your config in the same folder as your project, or if you want to share a config across projects, use this.

If no config file is found, haml-lint will use its built-in defaults.

Disabling Linter Rules

When you hover over a linting diagnostic, you can use the Quick Fix menu (lightbulb icon or Cmd+.) to:

• Disable in this project: Adds the rule to your project's .haml-lint.yml file
• Disable globally: Adds the rule to your VS Code user settings (hamlHero.globallyDisabledLinters), applying to all projects. This overrides any local config

You can also manually manage globally disabled rules in your VS Code settings:

{
  "hamlHero.globallyDisabledLinters": ["IdNames", "ClassesBeforeIds"]
}

Inline Disable Comments

For one-off suppressions, haml-lint supports inline disable comments that you can add manually:

-# haml-lint:disable IdNames
#my_id Content here
-# haml-lint:enable IdNames

Or to disable for the rest of the file:

-# haml-lint:disable IdNames
#my_id Content here
#another_id More content

Disabling RuboCop Rules

HAML-lint integrates with RuboCop to lint the Ruby code embedded in your HAML templates. You can disable specific RuboCop cops using the Quick Fix menu:

When you hover over a RuboCop diagnostic, use the Quick Fix menu (lightbulb icon or Cmd+.) to:

• Disable RuboCop rule in this project: Creates or updates .rubocop.yml in your project root with the disabled rule
• Disable RuboCop rule globally: Adds the rule to your VS Code user settings (hamlHero.disabledRubocopRules), applying to all projects

How RuboCop Config is Resolved

The extension uses the following strategy to apply RuboCop rules:

1. Local .rubocop.yml: If your project has a .rubocop.yml file, it is automatically detected and used by haml-lint. This is the standard way to configure RuboCop, and strongly preferred if you already use rubocop for your project.

2. Global VS Code settings: Rules added via hamlHero.disabledRubocopRules are merged with your local config. This allows you to maintain both project-specific and global RuboCop settings.

Configuration Examples

Local project config (.rubocop.yml):

Style/StringLiterals:
  EnforcedStyle: single_quotes
Lint/EmptyLine:
  Enabled: false

Global VS Code settings (automatically generated haml-lint config):

{
  "hamlHero.disabledRubocopRules": ["Style/DoubleNegation", "Metrics/LineLength"]
}

These are automatically merged during linting, so both your project and global settings apply together. Note that global settings are applied in the haml-lint config using the disabled_cops setting instead of using rubocop.yml

Known Issues

Linter warnings and errors highlight the entire line instead of just the offending code. This is an issue with haml-lint, and won't be fixed.

Format Document saves document when formatInBackground is true. It's more common in other linters for Format Document to format without saving. It's surprisingly difficult to determine whether formatting was triggered via command or on save. This is a low priority and probably won't be fixed. If this is an issue for you, disable formatInBackground.

Filter blocks (:ruby, :markdown) may not terminate correctly if there is trailing whitespace on the line after the end of the block.

Please add additional issues or feature requests to the GitHub repository.

Development

Setup

1. Install node/npm
2. Run npm install
3. Press F5 to open an extension development host
4. After any changes to TypeScript files run npm run compile and type Cmd+r in the extension development host to reload.

See docs/TESTING.md for details on syntax testing.

Enjoy!