Spintax — Sublime Text syntax highlighting

Syntax highlighting for spintax templates in Sublime Text — engine-accurate against the Modern Spintax Engine (@spintax/core) contract. Applies to .spintax files.

• Enumeration — {a|b|c}, empty option allowed: {|a|b}
• Permutation — [a|b|c], with config [<minsize=2;maxsize=3;sep=", ">a|b|c]
• Variable — %name%
• Local set — #set %name% = value — macro, re-rolled at every reference
• Local def — #def %name% = value — resolved once per render, held everywhere
• Include — #include "slug-or-id"
• Conditional — {?VAR?then|else}, {?!VAR?…}
• Plural — {plural %n%: one|few|many}
• Comment — /# … #/

Example

/# hero block #/
#set %product% = Acme
#def %tone% = {friendly|warm}
{Welcome to|Meet} %product% — %tagline%, trusted since {2019|2020}.
Ships with [<minsize=2;maxsize=3;sep=", ";lastsep=" and ">SSO|audit logs|alerts]{?free? — free tier available|}.
You have %n% {plural %n%: message|messages}.

Install

Package Control (recommended)

1. Open the Command Palette → Package Control: Install Package.
2. Search for Spintax and install.

Manual

Clone or download this repo into your Sublime Text Packages/ directory (Preferences → Browse Packages…) as a folder named Spintax.

What you get

• Full, engine-accurate tokenization of every spintax construct, including nested spintax inside conditional branches and enumerations.
• Correct permutation config vs HTML: <minsize=…;sep=…> is config, while HTML inside items ([<li>a</li>|b], [<a href="/x">…</a>|b]) stays content; genuine separators like [<and>a|b] and per-element [a<, >|b] are highlighted.
• Strict conditional / plural openers — {??x} and {plural noun} are not mis-highlighted.
• A URL fragment mid-sentence — https://example.com/#top — no longer opens a comment that greys out everything after it. The engine's rule is that /# opens a comment only when a #/ follows it somewhere in the document; a syntax definition sees one line at a time, so the grammar approximates: a /# closed on its own line always opens, and otherwise a comment opens only at the start of a line or after a blank. A /# at the start of a line with no #/ anywhere still greys the rest of the file — answering that needs the whole document.
• Toggle Comment (Ctrl/Cmd+/) wraps selections in /# … #/.

Nesting shades (optional)

Braces and brackets carry a cycling .depth-1 … .depth-4 scope suffix (depth 5 wears depth-1 again), the way Spintax Studio shades nesting — so you can see which closing bracket belongs to which opening one without counting. Default colour schemes render all depths alike; to shade pairs by level, add rules to your scheme (Preferences → Customize Color Scheme):

{
  "rules": [
    { "scope": "punctuation.section.braces.begin.spintax.depth-1, punctuation.section.braces.end.spintax.depth-1, punctuation.section.brackets.begin.spintax.depth-1, punctuation.section.brackets.end.spintax.depth-1",
      "foreground": "#e5c07b" },
    { "scope": "punctuation.section.braces.begin.spintax.depth-2, punctuation.section.braces.end.spintax.depth-2, punctuation.section.brackets.begin.spintax.depth-2, punctuation.section.brackets.end.spintax.depth-2",
      "foreground": "#61afef" },
    { "scope": "punctuation.section.braces.begin.spintax.depth-3, punctuation.section.braces.end.spintax.depth-3, punctuation.section.brackets.begin.spintax.depth-3, punctuation.section.brackets.end.spintax.depth-3",
      "foreground": "#c678dd" },
    { "scope": "punctuation.section.braces.begin.spintax.depth-4, punctuation.section.braces.end.spintax.depth-4, punctuation.section.brackets.begin.spintax.depth-4, punctuation.section.brackets.end.spintax.depth-4",
      "foreground": "#56b6c2" }
  ]
}

Development

Tokenization is verified with Sublime Text's own syntax test runner. The assertions live in tests/syntax_test_spintax.spintax and cover every construct plus the tricky discriminators (permutation config vs. HTML, leading/trailing separators, strict conditional/plural openers). CI runs them against Sublime Text latest, stable, and an ST3 build via SublimeText/syntax-test-action.

Run them locally from Sublime Text with Build With: Syntax Tests (Ctrl/Cmd+B) while the test file is open.

Known limits and ideas — including what a plugin backed by the Python engine would add that a syntax definition cannot — live in docs/TODO.md.

Releases are published from tags: tag a commit X.Y.Z and push it, and the release workflow creates the GitHub Release using the matching ## X.Y.Z section of CHANGELOG.md as its notes — so that section has to exist first. Package Control installs from tags, so a tag is the release; the GitHub Release entry is the shop window.

The VS Code sibling additionally verifies the mirrored TextMate grammar headlessly (vscode-tmgrammar-test) under the real Oniguruma engine.

Related

• 📖 Syntax reference — https://spintax.net/docs/syntax
• 🧪 Live playground — https://spintax.net/play/
• 📦 Engine (@spintax/core) — https://www.npmjs.com/package/@spintax/core
• 🧩 VS Code extension — investblog/vscode-spintax
• 🖥️ Spintax Studio — a desktop spintax editor: two panes, live render, validation diagnostics, variant generation and export — investblog/spintax-studio · Microsoft Store

License

MIT — part of the 301.st toolset.