Rename a CSS class across the theme and saved content

By the end of this page a CSS class has a new name everywhere it is used: in the theme’s files, and in saved posts, pages, templates and patterns. Every step can be taken back.

The example renames hero-title to page-title. The steps are the tool calls an agent makes, in order, so you can follow along or check its work.

Before you start

Switch on two tool groups on the Settings tab: Theme files and Search and replace in content. See Tool groups and what each one allows.

You can hand the whole job to the agent with a prompt like this:

Rename the CSS class hero-title to page-title, in the theme files
and in saved content.
Search with whole-word matching first and show me the list of files.
Apply the theme changes as one change set.
For content, use class mode, and show me the dry run before the real run.

1. Find every use in the theme

The agent calls btm.theme-search:

{
  "pattern": "hero-title",
  "wholeWord": true,
  "exclude": "assets/vendor/**"
}

wholeWord treats a hyphen as part of a word, so hero-title-large and my-hero-title are not matched. The result lists each match with its file, line and text.

Check the list before going on. A match marked editable: false is in a file these tools cannot write, such as a PHP file. Change those by hand. Leave bundled libraries and minified files alone.

2. Read each file

For every file in the list the agent calls btm.theme-read-file:

{ "path": "assets/css/front-page.css" }

The result has the file’s contents and its hash. The hash is needed in the next step.

3. Write all the files as one change set

The agent calls btm.theme-apply-changes with the complete new contents of each file and the hash it read:

{
  "label": "Rename hero-title to page-title",
  "changes": [
    {
      "path": "assets/css/front-page.css",
      "contents": "<the complete new file>",
      "expectedHash": "<hash from step 2>"
    },
    {
      "path": "templates/front-page.html",
      "contents": "<the complete new file>",
      "expectedHash": "<hash from step 2>"
    }
  ]
}

Every file is checked first. If one of them changed since it was read, nothing is written and the agent is told which. Otherwise all files are written and the result carries a changeSetId. Keep it: it is how the whole batch is undone.

Look at templateOverrides in the result. A template listed there has a version saved in the Site Editor that takes precedence over the file. That saved version is content, and the next steps reach it.

4. Find every use in saved content

The agent calls btm.content-search in class mode:

{
  "pattern": "hero-title",
  "mode": "class"
}

Class mode matches hero-title only as a complete class name, in HTML class attributes and in a block’s own class setting. It covers posts, pages, other public content, and saved templates, template parts and patterns.

5. Preview the replacement

The agent calls btm.content-replace. Without dryRun it is a dry run and writes nothing:

{
  "replacements": [
    { "from": "hero-title", "to": "page-title" }
  ],
  "mode": "class"
}

The result lists each post that would change, with before and after previews, and a token. Read the previews. A post listed as locked is open in someone’s editor. A post listed as no-revisions will not be written, because it could not be undone.

6. Apply it

The agent repeats the call with the token:

{
  "replacements": [
    { "from": "hero-title", "to": "page-title" }
  ],
  "mode": "class",
  "dryRun": false,
  "token": "<token from step 5>"
}

Exactly the previewed posts are written. Each one gets a revision of its old content first, and the result gives that revision’s id as revisionBefore.

If the content search in step 4 came back in several pages, steps 5 and 6 are repeated for each page. Each dry run has its own token.

7. Check the result

• Run the searches from steps 1 and 4 again for hero-title. Both should come back empty.
• Open a page that used the class and look at it, signed out, with any page cache cleared.

Undo

• Theme files: the agent calls btm.theme-revert-change-set with the changeSetId from step 3. All files go back in one step.
• Theme files, without an agent: click Revert next to the change set on the Activity tab.
• Content: restore the revisionBefore revision of each post under Revisions in wp-admin. For a template or template part, the agent can call btm.template-restore-revision.

What this does not reach

• Classes written in PHP files, or built by a script at run time.
• CSS from other plugins, and CSS saved under Additional CSS.
• A class stored in a block setting other than the block’s own class field.

Search for the old name in your browser’s developer tools after the rename to catch these.