Conditions vs. variables
Conditions and variables both produce different outputs from a single source, but they solve different problems. Understanding when to use each prevents overcomplicating your content.
Conditions: show or hide
Conditions control which blocks of content appear in a given output. A conditional block is either included or excluded — there's no middle ground.
Use conditions when different audiences need different sections:
Admin users see a "User Management" section that end users don't
Windows users see Windows-specific installation steps, macOS users see macOS steps
Enterprise customers see SSO configuration that free users never need
The mental model: conditions are a filter. Content goes through the filter, and blocks that don't match the target's Publication target settings are removed.
Variables: swap values
Variables control what specific values appear in the content. The structure and flow of the content stays the same — only the inserted values change.
Use variables when the same sentence needs different values per output:
"Welcome to Acme Pro" vs. "Welcome to Acme Enterprise"
"Contact support at help@acme.com" vs. "Contact support at enterprise-support@acme.com"
"API base URL: https://api.acme.com" vs. "API base URL: https://api-staging.acme.com"
The mental model: variables are placeholders. The content structure is fixed; the values are filled in at publish time.
If you're unsure which to use, ask: "Is the same sentence usable for both audiences, just with different values?" If yes, use a variable. If you need entirely different sentences or sections, use a condition.
Decision guide
Situation | Use | Why |
|---|---|---|
A whole paragraph or section should appear for certain audiences but not others | Conditions | The content block itself is audience-specific |
A specific value (name, URL, number) should change between outputs | Variables | The sentence structure is shared; only the value differs |
Installation steps differ entirely by platform | Conditions | Each platform has its own procedure |
A download URL differs by platform but the instructions are the same | Variables | Same instructions, different URL value |
Certain users need extra warnings that others don't | Conditions | The warning block is audience-specific |
The product name differs between editions | Variables | Same sentence, different product name |
Using both together
Conditions and variables complement each other in the same topic:
A topic uses conditions to show admin-only sections and hide them from end users
The same topic uses variables to substitute the product name and support URL
Each Publication target settings selects a condition profile (which audiences to include) and a Create variable sets (which values to substitute). The The publishing pipeline applies conditions first (filter), then variables (replace).
The publishing pipeline processes conditions before variables. This means variable tokens inside a conditioned block that gets excluded are never evaluated — they don't cause errors or appear in the output.
Avoid overuse
If you find yourself creating dozens of condition values or variable keys, reconsider whether separate topics might be cleaner. Conditions and variables shine when content is mostly shared with a few differences. When content is mostly different with a few shared sections, separate topics with shared How component reuse works is usually simpler.
A good rule of thumb: if more than 40% of a topic is conditioned, the audiences may be different enough to warrant separate topics that share content through How component reuse works.
See also
Set up conditions — create dimensions and values for conditional content
Create variable sets — define key-value pairs for text substitution
Writing for multiple audiences — strategies for planning multi-audience content
The publishing pipeline — how conditions and variables are processed during publish
Publication target settings — configure condition profiles and variable sets per target