# Substitutions

> Canonical source: [Substitutions](https://docs.hellowes.com/substitutions/)

Substitutions find a piece of text and replace it with different text every time your project publishes. Use them to swap staging URLs for production URLs, fix a recurring typo, or update a brand name across your whole site at once.

## Where to find it

1. Open your project.
2. Go to Settings.
3. Scroll to the Substitutions section.

Only team admins see the Add substitution button. Other members can view the list.

## How it works

Each substitution is a rule with two parts:

- **Enter text to replace**: the exact text to search for.
- **Enter replacement text**: the text to swap it with.

When you publish, WCH scans the HTML of your published pages and replaces every occurrence of the find text with the replacement text.

- **Exact text match, not a pattern.** The find text is matched literally. There are no wildcards or regular expressions.
- **Case-sensitive.** `Home` and `home` are different text. A rule for one does not affect the other.
- **Replaces every match.** All occurrences on every page are replaced, not just the first one.
- **HTML pages only.** Substitutions run on your HTML files. They do not touch CSS, JavaScript, images, sitemap.xml, or robots.txt.
- **Rules run in order.** Rules are applied one after another in the order they were added. A later rule can match text that an earlier rule just produced.
- **No duplicates.** WCH rejects a rule whose find and replace text both match an existing rule.

## When substitutions run

Substitutions are applied automatically as the final step of every publish that renders pages. You do not trigger them separately. That includes:

- Publishing a single page or a selection of pages
- Publish all pages
- Publishes started by a Webflow webhook
- CMS item publishes started by a CMS webhook

Publish and Promote to a destination package the pages that were already rendered, so the substituted text is what your destination receives. Adding a rule after a publish does not change existing pages until you publish again.

## Adding a substitution

1. In the Substitutions section, click Add substitution.
2. In Enter text to replace, type the exact text you want to find.
3. In Enter replacement text, type what it should become.
4. Save. The rule takes effect on your next publish.

You can add as many rules as you need. Each one is listed with its find and replace values.

## Changing or removing a rule

Rules cannot be edited in place. To change one, delete it and add a new rule with the corrected text. Deleting asks you to confirm, and the deletion cannot be undone. Pages already published keep the old text until you publish again.

## Keep your rules as specific as possible

> **A substitution replaces every match across every page.** An overly broad rule changes text you never meant to touch. A rule that replaces `link` or `the` matches those letters inside countless words, inside attribute values, and inside script tags, and quietly corrupts your pages.

To avoid unintended replacements:

- **Match the longest, most unique string you safely can.** Prefer `https://staging.example.com/` over `staging` or `example`.
- **Include surrounding context.** Replace `"oldbrand.com` with the leading quote, or `/oldbrand` with the leading slash, rather than the bare word.
- **Avoid short or common words** such as `home`, `the`, or single characters. They match far more than you expect.
- **Remember it is case-sensitive.** If the target text appears in different capitalizations, add a rule for each.
- **Mind the order.** If rule B's find text could appear in rule A's replacement text, rule B will rewrite A's output. Check the list order when rules overlap.

## Testing your rules

1. Add the rule.
2. Open Rendering, tick one page, and click Publish selected.
3. Open the staging site and check that page.
4. Once it looks right, click Publish all pages on the Dashboard.

If a substitution produces an unexpected result, delete it, add a narrower rule, and publish again.