# Spintax

> Spintax is a template syntax for generating many variants of a text from one source:
> `{blue|grey|clear}` picks one option, `[a|b|c]` shuffles a list, `%var%` interpolates,
> and conditionals and plural agreement keep the result grammatical. spintax.net is the
> canonical reference for that syntax and the home of its open-source engines for
> JavaScript, PHP and Python.

Every page listed here is available as clean Markdown by appending `.md` to its URL, and the
links below already point at the Markdown. The documentation core is also concatenated into
https://spintax.net/llms-full.txt for a single fetch.

This index is English. The site itself is published in 16 languages under `/{lang}/` paths
(for example `/ru/docs/syntax`); the long-form guides exist in English and Russian only.

## Start here

- [What is spintax](https://spintax.net/what-is-spintax.md): The primer: what spintax is, where the syntax came from, and the AI-drafts-the-template workflow it is used for today.
- [Spintax — overview](https://spintax.net/index.md): Landing page: the engine in one screen — enumerations, permutations, variables, nested templates, conditionals, plurals, and the packages that implement them.
- [Documentation hub](https://spintax.net/docs.md): Index of every guide and reference page on the site.

## Syntax reference

- [Spintax syntax reference](https://spintax.net/docs/syntax.md): The canonical reference for every construct: {a|b} enumerations, [a|b|c] permutations with <config>, %variables%, #set / #def / #include directives, {?VAR?then|else} conditionals, {plural N: form|form} agreement, comments, and post-processing.
- [Nested spintax](https://spintax.net/docs/nested-spintax.md): How nesting resolves, how deep it can go, and how variant counts multiply — the part most engines get wrong.

## Authoring guides

- [1. The authoring mindset](https://spintax.net/docs/authoring-mindset.md): Reverse authoring: write the finished text first, then open it up into a template. The workflow the rest of the series builds on.
- [2. Variables and multi-site reuse](https://spintax.net/docs/variables.md): Scope precedence (runtime > local > global), the re-roll gotcha, separator collisions, and reusing one template across sites.
- [3. Permutations in practice](https://spintax.net/docs/permutations.md): Ordered lists that shuffle: the serial-list pattern for titles and headings, size clamps, separators and last-separator handling.
- [4. Grammar-safe synonymization](https://spintax.net/docs/grammar-safe-spintax.md): Binding rules that keep swapped words grammatical — agreement, prepositions, articles; the Russian edition adds noun cases.
- [5. Template composition](https://spintax.net/docs/template-composition.md): Variables as rendered chunks: the item → section → orchestrator pipeline, walked through on a payment-methods block.
- [6. Conditional spintax](https://spintax.net/docs/conditional-spintax.md): {?VAR?then|else} value-driven branching: the three forms, the truthy/falsy table, the two-pass pipeline, and the anti-patterns.
- [7. Plural agreement](https://spintax.net/docs/plural-spintax.md): {plural <count>: form|form|form}: Russian 3-form vs English 2-form arity, numeric edge cases, the #def-not-#set count trap, and how it compares to ICU MessageFormat.
- [Spintax by example](https://spintax.net/examples.md): A worked example: the homepage "About Spintax" copy reverse-authored into a rich template — variables, permutations, conditionals, plurals and Russian cases — with real renders. The capstone of the authoring series.
- [Writing spintax templates with AI](https://spintax.net/ai-spintax-templates.md): The AI-to-template workflow: which documentation surface to feed a model (this file, the agent skills, the .md mirrors), the prompt, the MCP setup that lets a model validate its own output, and the nine mistakes models reliably make in spintax.
- [Spintax for cold email](https://spintax.net/spintax-for-cold-email.md): What the rest of the syntax buys an outreach campaign: permutations for order and length, conditionals for lines that depend on the data, plural agreement. Measured — one five-line email goes from 59,049 combinations to 8,503,056 — plus the render-then-upload workflow for senders that only parse {a|b|c}.

## Engines and packages

- [Spintax for n8n](https://spintax.net/spintax-for-n8n.md): The n8n community node (n8n-nodes-spintax): eight operations — Render, Render Many, Validate with a Valid/Invalid split, Build Authoring Prompt, Build Repair Prompt, plus Lint, Uniqueness and Protect Placeholders. One Render-per-row flow serves lead lists and product feeds alike; the LLM authoring funnel validates and repairs its own templates; Lint judges the render rather than the template, Uniqueness judges the pool, and Protect Placeholders carries a second engine’s macros through untouched. Zero dependencies, no credentials.
- [@spintax/core — the JavaScript engine](https://spintax.net/spintax-for-javascript.md): The npm package: install, quick start, API surface (render / validate / parse / analyze / neutralize), and the parity contract. MIT, zero dependencies.
- [spintax/core — the PHP engine](https://spintax.net/spintax-for-php.md): The Composer package for PHP 8.0+, extracted from the WordPress plugin: API, injected RNG, and what it deliberately does not have. MIT, zero dependencies.
- [Spintax engines — the family](https://spintax.net/spintax-engines.md): The four independent engines (JavaScript, PHP, Python, Object Pascal) held to one shared golden corpus: install, quick start and per-engine ergonomics. Pick by runtime. MIT, zero dependencies.
- [Playground](https://spintax.net/play/): Interactive editor: renders templates in the browser through @spintax/core, with inline validation. Not a document — visit it in a browser.

## Optional

- [Why spintax engines break Russian plurals](https://spintax.net/russian-spintax-plurals.md): The pain piece: the workarounds authors resort to when an engine has no plural primitive, and what a real fix looks like.
- [Designing the plural primitive](https://spintax.net/spintax-plural-design-trace.md): Engineering diary: trigger, spec lockdown, the reconciliation when the working implementation diverged from the abstract spec, then the PHP port.
- [What AI content actually costs](https://spintax.net/ai-content-costs.md): Per-article API pricing for Claude, GPT, Gemini, Grok, DeepSeek, Qwen and Mistral, how cache and batch discounts change the maths, and where templating beats per-article generation.
- [Spintax editors](https://spintax.net/spintax-editor.md): Where to edit spintax: VS Code and Sublime Text extensions with engine-accurate highlighting, the in-browser playground — and the archived Generating The Web (GTW) desktop app whose syntax became the standard.