BDD Gherkin Format

Clean, aligned, colored .feature files — and tables that behave like a spreadsheet.

Format Document, table alignment, and syntax highlighting for Gherkin in VS Code and Cursor. Works with Cucumber, Reqnroll, SpecFlow, Behave, Godog — any .feature file.

Why Gherkin Format

• One shortcut, consistent files. Format Document (or format on save) fixes indentation for Feature, Rule, Scenario, steps, Examples, comments, and descriptions.
• Tables that line up. Columns are padded as you type, numbers are right-aligned, and Tab moves between cells.
• Paste from Excel or Google Sheets. A copied range becomes an aligned Gherkin table.
• Lightweight on purpose. Formatting and colors only — no language server, no step index, nothing running in the background to compete with your navigation extension.

Quick start

1. Install BDD Gherkin Format:
   • VS Code: Extensions view, or ext install anghelll.bdd-gherkin-format.
   • Cursor, VSCodium, and other Open VSX editors: search BDD Gherkin Format in Extensions (Open VSX listing).
2. Open any .feature file. Syntax colors apply right away.
3. Run Format Document (Shift+Alt+F / Shift+Option+F). Format on save is on by default for Gherkin.

If another Gherkin formatter is installed, make this one the default:

"[gherkin]": {
  "editor.defaultFormatter": "anghelll.bdd-gherkin-format",
  "editor.formatOnSave": true
}

Features

Formatting

• Indents Feature / Rule / Background / Scenario / steps / Examples / tables (2 spaces by default, or your editor tab size).

• Places # comments, @tags, and free-text descriptions at the right depth.
• Format Selection for just part of a file.
• Optional style rules: one space after step keywords, aligned step keywords, one @tag per line, blank lines between scenarios, reindented DocStrings.

Tables like a spreadsheet

• Tab / Shift+Tab move between cells and realign; Tab on the last cell adds a row. Tab keeps its usual job when a completion, Copilot suggestion, or snippet is active.
• Align as you type: closing a cell with | pads the column without moving the cursor.
• Enter on a table row inserts a new row with the same columns.
• Paste as Table from Excel, Google Sheets, or CSV (, or ;). Pasting inside a table appends rows.
• Copy Table for Excel puts the table under the cursor on the clipboard as TSV.
• Columns: insert left / right, move left / right, delete.
• Sort rows by the current column, ascending or descending; the header row stays put.

All table commands are in the editor context menu under Gherkin Table and in the Command Palette (Gherkin:).

Syntax highlighting

• Structural and step keywords, # comments, @tags, quoted strings, <placeholders>, numbers, and DocString fences.
• Embedded highlighting inside DocStrings typed as json, xml, sql, yaml / yml, or html.
• Colors come from your current VS Code theme.

Editor comfort

• Folding, Outline, breadcrumbs, and sticky scroll by Feature / Rule / Scenario / Examples.
• Expand selection from a placeholder or step up to the scenario and feature.
• Snippets: feature, rule, background, scenario, outline, examples, docstring.
• # language: switches keywords between English (default), Spanish, and Portuguese. All official English synonyms are recognized (Example, Scenario Template, Scenarios, Business Need, Ability, *).

Same format in CI

The formatter also ships as the gherkin-format command, so a pull request can fail when a .feature file isn't formatted the way the editor would format it.

gherkin-format --check            # list unformatted files, exit 1 if any
gherkin-format --write features/  # fix them in place
gherkin-format --stdin < a.feature

Paths can be files or folders (the current folder by default). Build folders such as node_modules, bin, and obj are skipped, and LF / CRLF line endings are kept.

Commit a .gherkin-format.json and everyone — editor and CI — formats the same way. The nearest file above a .feature wins over personal settings, and the editor validates and autocompletes it:

{
  "indentSize": 2,
  "alignNumbers": true,
  "tagLayout": "preserve",
  "blankLines": "preserve"
}

It accepts the same options as the settings below: indentSize, alignNumbers, keywordSpacing, alignStepKeywords, tagLayout, indentDocStrings, blankLines.

What it doesn't do

Gherkin Format only handles how a .feature file looks. It does not:

• Resolve steps to their bindings or color steps as bound / unbound
• Offer step autocomplete, diagnostics, or binding generation
• Run tests

For step navigation and diagnostics, install BDD Guardian.

Why not Cucumber Official or Cucumber Full Support?

Those extensions bundle formatting with their own step resolver. If you also use a navigation extension, you get two resolvers that can disagree. Gherkin Format gives you the formatting and colors without the second resolver.

Works well with

Gherkin Format is one piece of the ForgeOne BDD family. Each extension does one job.

Get Format and Guardian together with the BDD ForgeOne extension pack.

Settings

A .gherkin-format.json in the project overrides these for the files below it.

Learn more

• What's new
• Roadmap
• Contributing

Found a formatting case that looks wrong? Open an issue with a snippet of the .feature. MIT License.