Skip to main content
Table of Contents

Understanding Variables

Variables let you swap out one piece of text (like your brand name) everywhere it's used across articles and Clips, so you only ever have to update it in one place.

Rebecca Thompson
Updated by Rebecca Thompson
Table of Contents

Got a bit of text you reuse everywhere, like your product or brand name?

Variables (sometimes called placeholders or merge tags) let you store it once and drop it into as many articles (and Clips) as you like. Update the Variable and every place it's used updates too.

And they look just like your normal text in your article. Heres a Variable we actually use all the time: ⋯ More. Looks just like text, right?

When should you use a Variable? 🤔

Variables are great for short bits of text that show up all over your docs and might change down the line:

  • Brand or product names.Especially handy if you're mid-rebrand or referring to a product that's still finding its name.
  • Support contact details.An email address or phone number that shows up across dozens of articles.
  • Anything else that repeats.A plan name, a URL, a version number. Anywhere you'd otherwise have to hunt down every mention by hand.
Variables only hold plain text, not HTML. For reusable HTML blocks or bigger chunks of content, reach for a Clip instead.
🧱 This article refers to our new Block editor. Older articles may use our Classic text editor.
You can upgrade an older article to the new Block editor at any time in the article's ⋯ More menu, or contact support to upgrade all articles at once.

  1. Head to Clips → Variables tab (or click here)
  2. Click + New Variable
  3. Give it a name and a value
  4. Hit Save
  1. Head to your article
  2. Type / to open the slash menu (or use the block menu or toolbar) and select Variable
  3. Search for your Variable and select it
  4. Your Variable appears in your article, showing its current value 🎉
A Variable in an article always shows the value it currently has, wherever it's inserted. There's no static or dynamic choice to make like with Clips.
  1. Head to Clips → Variables tab (or click here)
  2. Select the Variable you want to change
  3. Update its value and hit Save
Click on a Variable to see the "Used in" panel, which lists every article referencing it (plus any Clips it's embedded in) so you know exactly what you're about to change before you save.
  1. Head to Clips → Variables tab (or click here)
  2. Select the Variable you want to delete
  3. Click the ⋯ More button
  4. Click Delete
  1. Head to Clips → Variables tab (or click here)
  2. Select the Variable you want to lock
  3. Tick the Lock checkbox
  4. Hit Save

Overriding Variables Inside Clips

This is where Variables really pull their weight. Drop a Variable into a Clip and every article that uses that Clip inherits the Variable's value automatically. There's no need to retype it into each Clip instance.

But sometimes one article needs a different value than the rest. That's what overrides are for.

Insert the Clip as a Dynamic Clip and you can swap in a one-off value for a Variable in just that instance, without touching the Variable itself or the master Clip.

🤘 Example: Overriding Plan Name

Let's say you've got a Variable called Plan Name set to Starter, used inside a Dynamic Clip called SUPPORT: Upgrade Footer:

Need more from your Plan Name? Upgrade any time from your account settings.

Insert that Clip into a handful of articles and they all read "Need more from your Starter plan..." automatically. But your Enterprise onboarding guide should say Enterprise instead:

  1. Insert SUPPORT: Upgrade Footer into the article as a Dynamic Clip
  2. Click the inserted Clip and choose Edit variables
  3. Find Plan Name in the list and set the override to Enterprise
  4. Hit Save

Now that one article reads "Need more from your Enterprise plan..." while every other article using the same Clip keeps showing Starter. Change the Plan Name Variable itself later and every non-overridden instance updates too. The override just carves out an exception for that one placement.

Overrides only work on Dynamic Clips. A Clip inserted as static bakes in whatever the Variable's value was at insert time, so there's nothing left to override.

Using Variables With Custom HTML Clips

Variables get really handy once you pair them with an HTML block inside a Clip. Build a styled component once, like a colored callout banner with its own custom CSS classes, and let non-technical teammates swap out its text without ever touching markup.

Say your design team ships three ready-made banner styles as HTML blocks, each with a different custom class:

<div class="hd-banner hd-banner--warning">
            ⚠️ Banner Text
          </div>

Turn each style into its own Clip, like BANNER: Info, BANNER: Warning, or BANNER: Danger, with the custom class baked into each one, and drop a shared Banner Text Variable inside each Clip where the message goes. Now a non-technical teammate doesn't need to write or edit any HTML to use them:

  1. Insert whichever Dynamic Clip matches the style they want (BANNER: Warning for an amber banner, BANNER: Danger for red, and so on)
  2. Click Edit variables and override Banner Text with their own message for that article

The variation (color, layout, whatever custom classes are involved) lives in which Clip they pick. The wording lives in the Variable override. Nobody has to open the HTML block or touch a class attribute to get either right.

Variables only replace visible text, not HTML attributes like class. So the class names themselves stay baked into each Clip variant rather than being swapped by the Variable. That's why the "variation" is a choice of Clip, not a Variable value.

What did you think of this doc?

Using help.new to Create Articles

Collaborating on Articles with Presence

Get in touch