Substitutions

Substitutions automatically find a piece of text and replace it with different text every time your project publishes, perfect for swapping staging URLs for production URLs, fixing a recurring typo, or updating a brand name across your whole site at once.

Where to find it

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

How it works

Each substitution is a simple 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 your published pages and replaces every occurrence of the find text with the replacement text. A few things to know:

• Exact text match, not a pattern. The find text is matched literally. There are no wildcards or regular expressions. What you type is exactly what it looks for.
• Case-sensitive. Home and home are treated as different text. A rule for Home will not affect home.
• Replaces every match. All occurrences are replaced, not just the first one.
• Applies to your HTML pages. For a normal publish (a single page, or Publish All), substitutions run on your published HTML files.

When substitutions run

Substitutions are applied automatically during publishing. You don't trigger them separately. Set the rules once and they apply on every publish going forward, including:

• Publishing a single page or asset
• Publish All (a full project publish)
• Push to production
• CMS-triggered publishes

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, and you can delete a rule at any time.

Testing your rules

Because substitutions change your live output, it's wise to test before a full publish:

1. Add or edit the rule.
2. Publish a single page first and check that the result looks right.
3. Once you're confident, use Publish All.

If a substitution produces an unexpected result, delete or narrow the rule and republish.

—

⚠️ Keep your rules as specific as possible

Because a substitution replaces every matching occurrence across all your pages, an overly broad rule can change text you never intended to touch. For example, a rule that replaces link or the would match those letters inside countless words and quietly corrupt your pages.

To avoid unintentional replacements:

• Match the longest, most unique string you safely can. Prefer https://staging.example.com/ over just staging or example.
• Include surrounding context so the text can't match somewhere unexpected, for instance, replace "oldbrand.com" (with the quotes or a leading slash) rather than the bare word oldbrand.
• Avoid short or common words like home, the, or single characters. They will match far more than you expect.
• Remember it's case-sensitive. If your target text appears in different capitalizations, you may need a separate rule for each.