CodeAlign

Universal text alignment extension for Visual Studio Code.

CodeAlign aligns variables, operators, comments, tables, configuration files and any text structure - across every language and file format supported by VS Code.

Table of Contents

• Overview
• Features
• Installation
• Usage
• Commands
• Keyboard Shortcuts
• Auto-Align
• Configuration
• Alignment Rules
• Examples
• Supported Languages

Overview

CodeAlign is a dedicated alignment tool, not a formatter. It does not modify indentation, style or syntax - it only aligns separators vertically within qualifying groups of lines.

The alignment engine works entirely on raw text, making it language-agnostic and compatible with any file format VS Code can open.

Features

Feature	Description
Smart auto-detection	Detects the most appropriate separator in the selected lines and aligns accordingly. No configuration needed for common cases.
Group-based alignment	Only consecutive lines that share the same separator and the same indentation level are aligned together. Isolated lines are never touched.
Comment-aware	Separators found inside comments (// ..., # ..., -- ..., ; ...) are completely ignored. A commented-out line never influences the alignment of surrounding code.
String-aware	Separators found inside string literals ('=', "key => value") are ignored. Only separators in actual code positions are considered.
Parenthesis-aware	For =, occurrences inside parentheses are ignored. This prevents for-loop initialisers (for (let i = 0; ...)) and function parameter defaults from being treated as alignment targets.
Inline comment alignment	Aligns inline comments (//, #, --, ;) to the same column across consecutive lines, separately from separator alignment.
Multi-column alignment	Combines separator alignment and comment alignment in one pass, producing fully structured output with both columns aligned.
Auto-align	Optional background alignment that runs automatically on save or while typing, without any manual action required.
Custom separator	Any character or sequence can be used as the alignment target via the custom separator command.

Installation

1. Open VS Code
2. Press Ctrl+Shift+X to open the Extensions panel
3. Search for CodeAlign
4. Click Install

Usage

1. Select the lines you want to align
2. Press Ctrl+Alt+A (smart auto-detect) or open the Command Palette (Ctrl+Shift+P) and type CodeAlign
3. Choose the appropriate command

CodeAlign is also accessible via the right-click context menu under the CodeAlign submenu.

Commands

All commands are available in the Command Palette (Ctrl+Shift+P) under the CodeAlign category.

Command	Description
Align Smart (Auto-detect)	Detects the best separator and aligns
Align by =	Aligns assignment operators
Align by :	Aligns colon separators (YAML, JSON, dicts)
Align by |	Aligns pipe separators (tables, Markdown)
Align by => or ->	Aligns arrow operators
Align Inline Comments	Aligns inline comment markers to the same column
Align Multi-Column	Aligns separator then aligns inline comments
Align by Custom Separator...	Prompts for any separator string
Unalign (Collapse Spaces)	Reverses alignment: collapses padded spaces around the detected separator and inline comments back to a single space
Set Alignment Distance	Sets the minimum spaces before the separator
Toggle Auto-Align	Enables or disables automatic background alignment

Keyboard Shortcuts

Shortcut (Windows / Linux)	Shortcut (macOS)	Command
Ctrl+Alt+A	Cmd+Alt+A	Align Smart (Auto-detect)
Ctrl+Alt+C	Cmd+Alt+C	Align Inline Comments
Ctrl+Alt+U	Cmd+Alt+U	Unalign (Collapse Spaces)

All shortcuts are only active when text is selected and the editor is focused.

To rebind them to your own preference, open the Keyboard Shortcuts editor (Ctrl+K Ctrl+S), search for CodeAlign and assign any key combination you want.

Auto-Align

CodeAlign can automatically align your code as you work, without requiring any manual trigger.

Enabling auto-align

• Press Ctrl+Shift+P and run CodeAlign: Toggle Auto-Align
• Or click the CodeAlign item in the status bar (bottom right)

The status bar shows the current state at all times:

CodeAlign: auto (onSave)    -- auto-align is active
CodeAlign: manual           -- auto-align is off

Trigger modes

onSave (default): alignment runs each time you save the file. This is the recommended mode - it is non-intrusive and does not interfere with typing.

onType: alignment runs automatically after a short delay following your last keystroke. Useful for real-time feedback. The delay is configurable (autoAlign.debounceMs, default 400 ms).

Auto-align scope

By default, auto-align only processes the = separator to avoid unintended changes in complex files. You can extend this list via the codealign.autoAlign.separators setting.

Configuration

All settings are available under File > Preferences > Settings by searching for CodeAlign, or by editing your settings.json directly.

General

Setting	Type	Default	Description
codealign.minimumSpacesBefore	number	1	Minimum spaces between the content and the separator
codealign.minimumSpacesAfter	number	1	Minimum spaces after the separator
codealign.commentSeparators	string[]	["//","#","--",";"]	Comment prefixes used to detect and align inline comments
codealign.smartSeparators	string[]	["="]	Separator candidates for smart auto-detection
codealign.commentMinSpaces	number	2	Minimum spaces between code and an inline comment
codealign.excludedLanguages	string[]	[]	Language IDs where CodeAlign is disabled
codealign.smartDetectionThreshold	number	0.5	Fraction of lines that must contain a separator for it to be chosen

Default smart separator: = only.

To enable additional separators, add them to codealign.smartSeparators in your settings. The full list of available values, in recommended priority order:

:=  =>  ->  <-  !=  ==  =  :  |  ,

Multi-character operators must be listed before single-character ones to avoid false matches. For example, => must come before =, and := before :.

Example - enable =, : and =>:

"codealign.smartSeparators": ["=>", "=", ":"]

In the VS Code settings UI each entry shows a dropdown with all valid choices, so you can pick separators without typing them manually.

Auto-align

Setting	Type	Default	Description
codealign.autoAlign.enabled	boolean	false	Enable automatic alignment
codealign.autoAlign.trigger	string	"onSave"	"onSave" or "onType"
codealign.autoAlign.debounceMs	number	400	Delay in milliseconds for onType mode
codealign.autoAlign.separators	string[]	["="]	Separators processed during auto-alignment

Example settings.json

{
  "codealign.minimumSpacesBefore": 1,
  "codealign.minimumSpacesAfter": 1,
  "codealign.autoAlign.enabled": true,
  "codealign.autoAlign.trigger": "onSave",
  "codealign.autoAlign.separators": ["=", ":"]
}

Alignment Rules

Grouping

Lines are grouped for alignment only when all of the following conditions are met:

1. Consecutive: each line in the group immediately follows the previous one, with no blank lines or lines missing the separator in between.
2. Same indentation: all lines in the group start with the exact same leading whitespace. A change in indentation level starts a new group.
3. Minimum size: a group must contain at least two lines. An isolated line with a separator is never modified.

Separator filtering

The following occurrences are ignored when searching for a separator:

• Separators inside string literals: '=', "key: value", etc.
• Separators inside comments: // align =, # key: val
• For = specifically: occurrences inside parentheses such as for-loop headers (for (i = 0; ...)) and function parameter defaults

Operator disambiguation

CodeAlign distinguishes single-character operators from their multi-character counterparts:

Looking for	Ignores
=	==, !=, <=, >=, :=, =>, and compound assignments +=, -=, *=, /=, %=, &=, \|=, ^=, ~=, ??=
:	::, :=
\|	\|\|

Mixed indentation (tabs vs spaces)

When grouping lines for alignment, CodeAlign normalises leading whitespace using the editor's current tabSize. A line indented with one tab and a line indented with the equivalent number of spaces are treated as the same indentation level and grouped together. The actual indentation characters are preserved - only the comparison is normalised.

Examples

Variable assignments

Before:

const name = "John";
const age = 30;
const city = "New York";

After Align by =:

const name = "John";
const age  = 30;
const city = "New York";

YAML / configuration

Before:

host: localhost
port: 5432
database: mydb
password: secret

After Align by ::

host     : localhost
port     : 5432
database : mydb
password : secret

Arrow operators

Before:

const map = {
    home: path => "/",
    about: path => "/about",
    contact: path => "/contact/us",
};

After Align by =>:

const map = {
    home    : path =>  "/",
    about   : path =>  "/about",
    contact : path =>  "/contact/us",
};

OR

const map = {
    home: path      =>  "/",
    about: path     =>  "/about",
    contact; path   =>  "/contact/us",
};

Inline comments

Before:

name = "John"  # user name
age = 30  # user age
city = "NYC"  # location

After Align Inline Comments:

name    = "John"  # user name
age     = 30        # user age
city    = "NYC"    # location

Multi-column

Before:

name : value # comment
username : admin # login
password : secret123 # auth

After Align Multi-Column:

name     : value      # comment
username : admin      # login
password : secret123  # auth

Unalign (collapse)

Reverses any previous alignment by collapsing the padded spaces around the detected separator and inline comments back to a single space. Useful before re-aligning with a different separator, or to produce a clean diff.

Before:

const name     = "John";       // user name
const age      = 30;           // user age
const city     = "New York";   // location

After Unalign (Collapse Spaces):

const name = "John"; // user name
const age = 30; // user age
const city = "New York"; // location

Compound operators are recognised and not modified - total += 1 stays as total += 1.

Group isolation

CodeAlign does not align across blank lines or indentation changes:

x = 1;                       // isolated (group of 1) - untouched

const name = "John";        // group 1 - aligned together
const age  = 30;

    let host = "localhost";  // group 2 (deeper indent) - aligned separately
    let port = 8080;

z = 99;                      // isolated (group of 1) - untouched

Comments and strings ignored

A line whose = only appears inside a comment or a string is excluded from every group:

const prev = idx > 0 ? line[idx - 1] : '';
const next = idx < line.length - 1 ? line[idx + 1] : '';
// Skip !=, <=, >=, :=, == and => in comments - this line is ignored
if (next === '-' || next === '=' || next === '<') { ... }  // '=' is inside a string

Only the two const lines form a valid group and are aligned. The comment line and the if line are excluded.

Parenthesis-aware (for-loops)

let depth = 0;
for (let i = 0; i < idx; i++) {   // = is inside () - excluded from alignment

The = inside for (...) is ignored. let depth = 0 is left as a group of one and is not touched.

Supported Languages

CodeAlign works on any file VS Code can open as text. It has been tested with:

Python, JavaScript, TypeScript, Rust, Go, C, C++, Java, Lua, PHP, Ruby, Swift, Kotlin, Bash, PowerShell, SQL, HTML, CSS, SCSS, JSON, YAML, TOML, XML, Markdown, Dockerfile, .env files, log files, and plain text.

Because the engine operates on raw text with no language parser, it is compatible with any format that uses consistent separator characters.

Changelog

0.1.1

• Fix: compound assignment operators (+=, -=, *=, /=, %=, &=, |=, ^=, ~=, ??=) are no longer mis-aligned by the = rule. A line like page_num += 1 is now left untouched instead of becoming page_num + = 1.
• Fix: lines indented with tabs and lines indented with the equivalent number of spaces are now grouped together. The comparison normalises whitespace to visual columns based on the editor's tabSize; actual indentation characters are preserved.
• New command: Unalign (Collapse Spaces) (Ctrl+Alt+U / Cmd+Alt+U) reverses alignment by collapsing padded gaps around the detected separator and inline comments to a single space.

0.1.0

• Initial release.

Contributing

Found a bug or have a feature in mind? Open an issue on GitHub - all feedback is welcome.

github.com/r-seize/CodeAlign/issues

When reporting a bug, include the text you were trying to align and the result you expected. For a feature request, a short description and an example is enough.