HAML - All in One

A powerful VS Code extension providing essential tools for efficient and seamless HAML development.

Features

The following features are supported to make your HAML development effortless:

| ✅ | Routes: Go to Definition | Rails Project | | ✅ | Split to Partial | | | ✅ | Convert HTML/ERB to HAML | html2haml gem | | ✅ | Snippets - HAML | | | ✅ | Snippets - Rails | | | ✅ | Wrap in Conditional | |

Linting

In a multi-root workspace each folder is linted by its own server, with its own Gemfile, working directory and .haml-lint.yml. Rails routes and asset completion use the first folder.

While a .haml file is open, a HAML item in the status bar reports the lint server: $(sync~spin) while it starts, $(check) once it is running, and $(warning) when it died or haml-lint is missing, with the reason in the tooltip. Clicking it opens the "Haml" output, also available as HAML: Show output.

This extension utilizes the haml-lint and rubocop gems for linting HAML files. To configure, create a .haml-lint.yml and .rubocop files in your project root. Check the default configuration.

To install the gem, add this to your Gemfile:

group :development, :test do
  gem 'rubocop'
  gem 'haml-lint', require: false
end

Features in Depth

Partials - Go to Definition

Navigate to a partial file by using CTRL + Click on the partial name or right-click and select Go to Definition.

Every way Rails names a partial is understood: render "shared/header", render partial: "row", render "row" (beside the current view), render @user and render @users, collection: ... (the object and its collection). When a partial exists in several templates — _row.html.haml next to _row.turbo_stream.haml, or a +mobile variant — all of them are offered. Partials under any app/views directory in the workspace are found, including an engine kept in the repository.

Partials - Split to Partial

Easily extract content into a new partial. Select the content, click the Create a partial from selection option in the Code Actions menu (lightbulb icon), and you're done!

Wrap in Conditional

Quickly wrap selected HAML content in a conditional statement. Select any content, access the Code Actions menu (lightbulb icon), and choose Wrap in conditional. You'll be prompted to enter the condition (e.g., user.present?, @items.any?, etc.).

Example: Before:

%div.user-info
  %h2= @user.name
  %p= @user.email

After wrapping in conditional with @user.present?:

- if @user.present?
  %div.user-info
    %h2= @user.name
    %p= @user.email

Partial Completion

Autocomplete for partials found under any app/views directory in your project. The list is indexed once and refreshed when partials are added or removed, so it does not scan the workspace on every keystroke.

Data Attributes Completion

Smart autocompletion for HTML data attributes, with specific support for:

• HTML Common Attributes: data-toggle, data-target, data-dismiss, etc.
• Rails UJS: data-confirm, data-method, data-remote, data-disable-with, etc.
• Turbo Rails: data-turbo, data-turbo-action, data-turbo-frame, data-turbo-stream, etc.
• Stimulus: data-controller, data-action, data-target, etc.

Works with all HAML attribute syntaxes:

%div{data_confirm: "Are you sure?"}
%form(data_remote: true, data_turbo_action: "replace")
%button{:data_disable_with => "Processing..."}

Simply start typing data- in any attribute context and get intelligent suggestions with descriptions. This works in any HAML project — a Rails app is not required.

Formatting and auto-correction

Format Document (and editor.formatOnSave) runs haml-lint's safe autocorrect over the whole file. The same correction is also exposed as a source.fixAll action, so it can run on save without editor.formatOnSave, or from the Source Action... menu:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.hamlLint": "explicit"
  }
}

Notes:

• With editor.formatOnSave also on, the autocorrect runs twice per save (the second pass changes nothing, but costs one round-trip to the lint server). Pick one.
• Large files with heavy RuboCop cops may need a higher editor.codeActionsOnSaveTimeout (VS Code's default is 750 ms); on timeout the file is saved unchanged.
• Every correction comes from the installed haml-lint. Its own linters (TrailingWhitespace, ClassesBeforeIds, HtmlAttributes, …) are only autocorrected from haml_lint 0.74.0 on; with an older gem the format still fixes RuboCop offenses, and the extension says so once per session.

The lightbulb on an offense haml-lint reports as auto-correctable offers "Fix all TrailingWhitespace offenses in this file (haml-lint autocorrect)". haml-lint corrects per linter, not per line, so the whole file is corrected for that linter (for a RuboCop offense, for every RuboCop cop). Unlike Format Document and source.fixAll.hamlLint, which only apply safe corrections, this action is an explicit ask and also applies the corrections haml-lint and RuboCop mark as unsafe. This relies on the correctable flag haml-lint reports since haml_lint 0.76.0; with an older version the lightbulb keeps working as before, without these actions.

Convert HTML/ERB to HAML

Convert existing HTML or ERB files to HAML using html2haml.

Installation:

gem install html2haml

Usage:

1. Open an HTML or ERB file.
2. Open the Command Palette (CTRL + SHIFT + P).
3. Search for HAML: Convert HTML to HAML and select it.
4. Watch the magic happen!

Configuration

You can customize this extension by creating a .vscode/settings.json file in your project root:

{
  "hamlAll.lintEnabled": true,

  // Lint while typing (debounced). When false, files are linted on open and save only.
  "hamlAll.lintOnType": true,

  // Use 'bundle exec' to run haml-lint.
  // (If true, the 'linterExecutablePath' setting is ignored.)
  "hamlAll.useBundler": false,

  // Path to the haml-lint executable. Used only to check that haml-lint is
  // available; linting itself runs through "hamlAll.rubyCommand".
  "hamlAll.linterExecutablePath": "haml-lint",

  // Ruby interpreter used to run the lint server. Set an absolute path when
  // rbenv/asdf/mise shims are not on the PATH of a GUI-launched VS Code.
  "hamlAll.rubyCommand": "ruby",

  // Command used to run Rails (project detection and `rails routes`).
  // May include arguments, e.g. "bundle exec rails".
  "hamlAll.railsCommand": "bin/rails"
}

Changing hamlAll.useBundler or hamlAll.rubyCommand restarts the lint server on the spot — no window reload.

hamlAll.linterExecutablePath, hamlAll.rubyCommand and hamlAll.railsCommand are machine-scoped: they can only be set in your user settings, never by a repository's .vscode/settings.json.

railsRoutes.railsCommand is deprecated in favour of hamlAll.railsCommand. It is still read when the new setting is not set.

Workspace Trust

In a workspace you have not trusted, the extension keeps syntax highlighting, snippets, completions, and go-to-definition working, and disables everything that runs the project's Ruby tooling:

• Linting and diagnostics (haml-lint / RuboCop)
• Formatting and quick fixes
• Rails routes completion and go-to-definition
• HAML: Convert HTML/ERB to HAML

This is deliberate: bin/rails, the Gemfile, and a require: directive in .haml-lint.yml are code from the repository. Trusting the workspace enables them immediately, with no window reload. For the same reason hamlAll.useBundler is ignored when it comes from a workspace's .vscode/settings.json in Restricted Mode.

Recommended Extensions

Enhance your experience with these complementary extensions:

• One Dark Dracula: A vibrant dark theme that pairs beautifully with this extension's syntax highlighting.
• Ruby LSP: Provides robust Ruby language support.

Acknowledgments

Special thanks to these extensions for inspiration and functionality:

• Better HAML (MIT License)
• Rails Open Partial (MIT License)
• HAML Lint (MIT License)
• Rails Partial (MIT License)
• Rails Routes (MIT License)

License

This extension is released under the MIT License.