Blog

You changed a URL, and now the old one returns a 404. Bookmarks, backlinks and Google’s index all still point to the old address. A 301 redirect in .htaccess tells the server to send every request for the old address to the new one, and it tells search engines the move is permanent.

Writing the rule is the easy part. The real risk is the file it lives in, because WordPress keeps its permalink rules there too. A misplaced line can do nothing at all, start a redirect loop or take the whole site down. This guide covers the safe order of work. If you are changing URLs as part of wider search work, our guide to doing SEO on WordPress explains where redirects fit.

Does your server read .htaccess at all?

Check this first. .htaccess is an Apache configuration file. Nginx ignores it. Kinsta’s documentation says its WordPress sites have no .htaccess file and points users to its MyKinsta redirect tools instead. WP Engine has deprecated .htaccess and recommends its own alternatives. On hosts like these, a perfectly valid rule does nothing, and nothing tells you so.

If your host’s control panel or documentation doesn’t say Apache, ask support which web server runs the site and whether it reads .htaccess rewrite rules. This matters most when staging and production run on different hosts: a rule that works on Apache staging can be dead weight on an Nginx production server. If the answer is no, use the host’s redirect tool, a redirect plugin or your CDN’s redirect rules. The patterns below won’t apply.

Where do 301 rules go in a WordPress .htaccess file?

Put them above the # BEGIN WordPress line, never between the BEGIN and END markers. WordPress owns that block and rewrites it whenever you save Settings > Permalinks, so anything you add inside it can disappear. Its last rule is a catch-all that hands every request that isn’t a real file to index.php. A RewriteRule placed below that catch-all may never run.

Before you edit:

1. Open the site root (often public_html) over SFTP or in your host’s file manager. Turn on “Show hidden files”, because names that start with a dot are often hidden. A missing-looking .htaccess is usually just hidden.
2. Download a copy of the file and keep the SFTP connection open, so you can put it back in seconds.
3. Edit in a plain-text editor. Curly quotes pasted from a word processor will break the file.

A working layout looks like this:

# BEGIN Custom redirects
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^old-page/?$ /new-page/ [R=301,L]
</IfModule>
# END Custom redirects

# BEGIN WordPress
# (WordPress-generated rules, leave untouched)
# END WordPress

Practitioners disagree on one detail. A Webmasters Stack Exchange answer argues that the simpler Redirect directive (mod_alias) is processed by a different module from WordPress’s RewriteRule lines (mod_rewrite), so its position in the file matters differently. The practical answer is to pick one module for your redirects. RewriteRule above the WordPress block is the most predictable choice, and you still test the result.

Which 301 rule fits your move?

Use Redirect for a quick one-off. Use RewriteRule when you need patterns, conditions on the host or protocol, or query strings. Two details catch people out. In .htaccess, Apache strips the leading slash before matching a RewriteRule, so patterns start with ^old-page, not ^/old-page. And literal dots in a pattern need escaping, as in \..

One page

Redirect 301 /old-page/ https://example.com/new-page/

Redirect matches a prefix and adds whatever follows it to the target. That means this rule also sends /old-page/child/ to /new-page/child/. If you want an exact match, use the RewriteRule version from the layout above. Include the trailing slash on the target too, or WordPress adds one with a second redirect.

A whole directory or category

RewriteRule ^category/guides/(.*)$ /resources/$1 [R=301,L]

(.*) captures the rest of the path, and $1 puts it back in the new location. Rules for specific pages that should go somewhere else must sit above this one. Apache works through the rules in order, so a broad rule placed first catches those pages before their own rules get a turn.

Old domain to new domain, keeping paths

RewriteCond %{HTTP_HOST} ^(www\.)?old-example\.com$ [NC]
RewriteRule ^(.*)$ https://new-example.com/$1 [R=301,L]

This works only if the paths stay the same on the new domain. If /shop/product-a/ has become /catalog/product-a/, add specific rules above this one. Keep the old domain registered and pointing at the server, or every one of these redirects stops.

HTTP to HTTPS and www to non-www in one hop

RewriteCond %{HTTPS} off [OR]
RewriteCond %{HTTP_HOST} ^www\. [NC]
RewriteRule ^(.*)$ https://example.com/$1 [R=301,L]

Separate rules for protocol and host stack into two redirects: http://www goes to https://www, then to https://. This combined rule does it in one response. Add it only after HTTPS works at the host. If the site sits behind a proxy or CDN that handles SSL, the origin may see every request as HTTP, and this rule loops. See the loop section below.

A URL with a query string

RewriteCond %{QUERY_STRING} ^p=123$
RewriteRule ^$ /new-post/ [R=301,L,QSD]

RewriteRule never sees the query string, so you match it with a condition. QSD drops the old ?p=123 from the target, so it isn’t carried over to the new URL.

How do you test a 301 before it sticks?

Write the rule as R=302 first. Apache’s per-directory rewrite guide recommends a temporary redirect while you debug, because browsers cache 301s. A wrong 301 can keep firing in your own browser even after you fix the file. Switch to 301 once every destination checks out.

Test from the command line, not only in a browser:

curl -sIL http://www.example.com/old-page/

This prints each response in order. You want one 301 (or 302 while testing) with the correct Location, then a 200. Check the old URL, the new URL, and the http, https, www and non-www versions of each. If you prefer a browser, use a private window.

Two or more 301s in that output is a chain. Google’s site-move documentation says Googlebot follows up to 10 hops but recommends redirecting straight to the final URL. If a chain can’t be avoided, Google says ideally no more than three hops and fewer than five. Point old rules straight at the final URL, and update your internal links so your own menus and posts skip the redirect entirely.

Check where each redirect lands, too. Google warns that a redirect to an unrelated page, like sending everything to the homepage, can be treated as a soft 404. If a page has no real replacement, a useful custom 404 page serves visitors better than a homepage redirect.

Why is the redirect doing nothing?

These are the common causes, roughly from most to least frequent:

1. The server doesn’t read the file. It runs Nginx, or the host has turned .htaccess off. Ask the host.
2. The rule sits below WordPress’s catch-all. Move it above # BEGIN WordPress.
3. Your browser cached an old response. Test with curl or a private window.
4. The pattern starts with ^/. Remove the slash.
5. A broader rule matched first. Put specific rules above general ones.
6. You edited the wrong file. Hosting accounts with several domains have several document roots, each with its own .htaccess.
7. mod_rewrite or AllowOverride is off. Only the host can change this.

Not every unexpected 301 comes from your file. WordPress issues its own canonical redirects, for example adding a trailing slash, and a redirect plugin may also be acting on the same URL. Pick one place to manage each redirect and check both.

How do you fix “too many redirects”?

Chrome shows ERR_TOO_MANY_REDIRECTS. Firefox says “The page isn’t redirecting properly”. The usual cause is two layers both trying to set the canonical address. WordPress’s Logging In handbook lists mismatched site URL settings, mixed HTTP and HTTPS values, and conflicting SSL or redirect settings at the CDN, proxy, host or server.

Work through the layers in order:

1. Settings > General: WordPress Address and Site Address must match the final URL exactly, protocol and www included. If WP_HOME or WP_SITEURL is set in wp-config.php, those values win.
2. Your .htaccess: comment out your HTTPS and www rules and test again.
3. SSL or redirect plugins: if one already forces HTTPS, remove your rule or switch the plugin’s redirect off. Keep one, not both.
4. The CDN: in Cloudflare, “Flexible” SSL serves HTTPS to visitors but connects to your server over HTTP. An HTTPS rule on the server then sends every request back round in a loop. Cloudflare’s troubleshooting docs cover switching the mode when the server has its own certificate.
5. Reverse proxies: WordPress’s HTTPS handbook warns that loops happen when the proxy terminates SSL and WordPress doesn’t read the X-Forwarded-Proto header.

Clear cookies and caches after each change, or you will be testing an old response.

What if the site returns a 500 after the edit?

A syntax error in .htaccess can stop every request. Upload your backup copy straight away. If you don’t have one, follow WordPress’s Common Errors handbook: rename the file to .htaccess_old, load the site, then go to Settings > Permalinks and click Save Changes to rebuild the default rules. Add your custom rules back one at a time, testing after each. Our guide to fixing a WordPress white screen covers the other causes if renaming the file doesn’t help.

If pretty permalinks then return 404 everywhere except the homepage, the WordPress block is missing or mod_rewrite is off. This is a different problem from a bad 301. Save permalinks again, then ask the host to enable mod_rewrite.

When should you stop and get help?

A handful of rules is a 20-minute job. A site migration is not. If you are moving hundreds of URLs, changing URL case, or consolidating sites, build a spreadsheet that maps each old URL to its closest live replacement first, and test a sample after launch. Get help if a loop persists across the CDN and host, if you can’t read the server error log, or if the whole site is down and the rename didn’t fix it. For WooCommerce product and category URL changes, turn on WooCommerce’s own 301 redirect option before you edit the permalinks. It avoids most of this.

If you’d rather not edit server files at all, SiteSelf can add and check 301 redirects on request through chat. Editing .htaccess needs hosting (SSH) access, and the agent reports what changed and what it checked.

Frequently asked questions

Can I change or remove a 301 later?

Yes. Edit or delete the rule and the server stops sending it. Browsers that already cached the 301 may keep following it for a while, though. That’s why you test with a 302 until the destination is final.

Do I need RewriteEngine On before my rules if WordPress already has it?

Add it to your own block anyway. It costs nothing, and your rules keep working if the WordPress block is removed or rebuilt. Repeating it does no harm.

Should I redirect every 404 to the homepage?

No. Google says redirects to irrelevant pages can be treated as soft 404s, and visitors get confused. Redirect old URLs to their nearest real equivalent, and let pages with no replacement return a proper 404.

Is .htaccess faster than a redirect plugin?

For a normal site with dozens or a few hundred redirects, the difference is too small to drive the decision. Choose by who maintains the redirects. A plugin suits people who don’t want to touch server files. .htaccess suits pattern rules and domain-wide moves on Apache.

Why did my custom rules disappear?

They were inside the WordPress block, or a plugin rewrote the file. Keep custom rules in their own commented section above # BEGIN WordPress. Check the file again after you save permalinks or update security and SSL plugins.

In WordPress, “template” can mean five different things. It can be a block template in the Site Editor, a PHP file in a classic theme, a WooCommerce template override, a page builder layout, or a demo design you imported when you set the site up. Most failed template edits happen in the wrong one of these.

So the job is not “edit the template”. It’s finding the layer that actually draws the page, making the change there, and checking that the change shows up, affects only what you meant, and survives the next update. This guide covers each route. If you want the broader picture of theme work first, see our guide to editing themes without losing work.

Which kind of template is your site using?

Start at Appearance in the dashboard. If you see an Editor item, you have a block theme. If you see Customize and no Editor, you have a classic theme. WordPress.org’s documentation says the Site Editor only appears when a block theme is active. If you’ve been looking for a template editor and can’t find one, this is usually why.

What you see	Theme type	Where templates live
Appearance > Editor	Block theme	Site Editor (saved in the database), plus HTML files in /templates and /parts
Appearance > Customize, no Editor	Classic or hybrid theme	PHP files such as single.php, page.php, header.php
A builder’s own template or theme-building menu	Either type	The builder’s own templates, with display rules
A woocommerce folder in your theme	Either type, store only	Override files that replace WooCommerce’s defaults

Next, work out whether your change is to content, to style or to structure. Six words in a hero is content: edit the page. A new button color everywhere is style: use Styles or Additional CSS. An author box on every post is structure: edit the template.

How to customize a block theme template in the Site Editor

On a block theme, you can change templates without writing code. Every template is shared, though, so check what else uses it before you save.

1. Go to Appearance > Editor > Templates. Open the template that controls the page type you want to change, such as Single Posts, Pages or Archive.
2. Edit the blocks. Headers and footers are template parts. A change to one appears on every page that uses that part.
3. Click Save. WordPress lists everything you’re about to save: templates, template parts, navigation and synced patterns. Read that list. If you see something you didn’t mean to touch, untick it.
4. To change colors, fonts or spacing across the whole site, use Styles instead. Styles keeps revisions, and you can reset it.

How to change the template for one page only

Leave the shared template alone. Someone on the WordPress.org forums edited a template they used for every page, trying to change just one of them, and lost earlier work. The advice they got applies to everyone. Edit that page’s content instead. Or create a new template, assign it to that page in the page’s settings sidebar, and build it from a non-synced pattern. A non-synced pattern is a plain copy, so editing it on one page leaves the others alone.

Why your file edit loses to the Site Editor

WordPress’s Theme Handbook sets the order. WordPress first looks for a template saved in the database through the Site Editor. Then it checks the child theme’s /templates folder, then the parent theme’s. It uses the first one it finds. So if anyone has ever saved that template in the Site Editor, nothing you change in the file over FTP will show.

To make the file count again, reset that template in the Site Editor. A reset deletes the saved version, so export or copy its block markup first. The handbook also notes that templates saved in the database never turn into theme files on their own. If you want a template to ship with the theme, copy its markup into the matching file yourself.

How to customize a classic theme template with a child theme

On a classic theme, templates are PHP files. WordPress picks the most specific file that matches each request. A page with the slug “about”, for example, uses page-about.php if it exists, and page.php if it doesn’t. Never edit the parent theme’s files. The next theme update replaces them, and your changes go with them. Put your changes in a child theme, which a parent update leaves alone. Practitioners report losing work to this mistake more than any other.

1. Back up the site. Ideally, work on a staging copy.
2. Create a folder in wp-content/themes, for example astra-child.
3. Add a style.css with a header. The Template line must match the parent theme’s folder name exactly, including capital letters.
4. Copy only the file you need from the parent into the child, at the same path and with the same filename, and edit the copy.
5. Activate the child theme under Appearance > Themes and check the page.

/*
Theme Name: Astra Child
Template: astra
*/

Your child theme’s stylesheet won’t always load on its own. The handbook says that depends on how the parent theme loads its styles. If your CSS isn’t applying, add this enqueue to the child theme’s functions.php:

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style( 'child-style', get_stylesheet_uri() );
} );

To give one page its own layout, create a file in the child theme that starts with <?php /* Template Name: Landing */ ?>. Then pick it from the Template field when you edit the page.

Child themes have limits. A child theme still depends on the parent, and some themes load their files with get_template_directory(). That function always points at the parent theme, so a copy in the child is ignored. The handbook also says a child theme isn’t always the right tool. If your design differs a lot from the parent’s, building a separate theme may be the better choice.

When Additional CSS is all you need

A lot of “template” requests are really styling: padding, a font size, a button color. On the WordPress.org forums, a non-coder who took over a site built by an agency had been installing plugins to adjust spacing. The fix was simpler. They right-clicked the element, chose Inspect to find the CSS rule, and pasted an override into Appearance > Customize > Additional CSS. As support pointed out in that thread, plugins are for adding features, not for CSS tweaks.

Theme updates don’t touch Additional CSS. It can’t change the HTML structure, though. If the element you want doesn’t exist in the page’s markup, you need the template layer. For block themes, the Styles panel is the equivalent place. We cover choosing between these layers in more detail in theme customization that survives updates.

How WooCommerce and page builder templates differ

To override a WooCommerce template on a classic theme, copy the file from wp-content/plugins/woocommerce/templates/ into a woocommerce folder in your child theme. Keep the same path, minus the templates folder. WooCommerce’s template documentation adds two traps. If your theme has a woocommerce.php file, WooCommerce uses that file instead of woocommerce/archive-product.php. And themes with custom templates have to declare WooCommerce support.

Overrides go stale. WooCommerce’s developer docs say your copies don’t update when WooCommerce updates its own templates. WooCommerce > Status > System Status lists your overridden templates and flags outdated ones. The fix is manual: back up your copy, copy the new default into its place, then redo your changes. WooCommerce says a one-click update isn’t practical, because themes are coded too differently. Our guide to updating a theme without losing work adds this check to the update routine.

Some parts of a product page are added by hooks rather than by a template file being loaded directly. In one WordPress.org support thread, copied overrides of price.php and product-image.php did nothing. WooCommerce support suggested removing the woocommerce_template_single_price action and adding a replacement that loads the template with wc_get_template(). Experienced store developers go further: use hooks where you can, and keep your overrides few and small.

On block themes, WooCommerce 10.2 moved its product block templates into the Site Editor, under All Templates > Add Template. Instructions written before September 2025 may point you to the wrong screen.

Page builders keep a template layer of their own. If a builder’s theme-building feature controls your shop or product pages, editing the WooCommerce page or a theme file won’t change them. Edit the builder’s template and check its display conditions.

Why your template change doesn’t show up

Work through these in order. The first two cause most cases.

1. A higher-priority template wins. A version saved in the Site Editor, a woocommerce.php file or a builder template is drawing the page, not the file you edited.
2. A cache is serving the old page. WordPress.org’s FAQ names the browser cache, the server cache and caching plugins. Add your CDN and object cache to that list. In the WooCommerce thread above, the overrides only appeared after the poster cleared the Redis object cache. Purge the caching plugin, the host cache, the object cache and the CDN. Then load the page in a private window.
3. You edited the wrong file or path. WordPress suggests a deliberately obvious test change, such as a block of red text. If it doesn’t appear, you’re editing a file the site doesn’t use.
4. The child theme is misconfigured. Check the Template value and the stylesheet enqueue, and make sure the copied file’s folders match the parent’s.

If the site shows “There has been a critical error on this website,” the change broke PHP. WordPress’s handbook says to check the admin email inbox, turn on debugging and read wp-content/debug.log. The file path in the error message tells you which file to fix or restore.

When to stop and get help

Visual changes in the right editor are well within reach for most site owners. Stop when the work moves into PHP and you don’t have a working backup or a staging copy. Stop too when a WooCommerce override is outdated on a store that’s taking orders, when a hooked template needs replacing, or when you’re switching themes or builders. A switch means rebuilding every post, archive and product template, not reskinning them. If you’d rather describe the change and have it done on your existing site, here is how SiteSelf handles design and template changes.

After any structural change, check two things the old template may have done for you. Can you still tab through the menus with a keyboard, and does every form field still have a label? And does each page still output exactly one canonical tag?

Frequently asked questions

Do I need a child theme to customize a template?

You need one for code changes to a parent theme that still gets updates. For style-only changes, Additional CSS or the Site Editor’s Styles is usually enough. For block template changes made in the Site Editor, the database copy already survives theme updates.

Is it safe to edit templates in the Theme File Editor?

It’s risky. One PHP typo can take the site down, and the editor doesn’t keep a copy of the previous version. If you use it at all, use it on a child theme and keep FTP or hosting file access ready so you can undo the change.

How do I reset a block template to the original?

Open the template in Appearance > Editor > Templates and use its reset or “clear customizations” option. That deletes your saved version and goes back to the theme’s file, so export or copy the markup first if you might want it again.

Why can’t I see the Template option on my page?

On a classic theme, the Template field only appears if the theme or child theme includes at least one custom page template. On a block theme, you may need to create the template in the Site Editor before you can assign it to a page.

Will my template customizations survive a theme switch?

Mostly not. Child theme files belong to the old parent theme. Block templates saved in the Site Editor belong to the old theme. Builder templates go with their builder. Plan a theme switch as a rebuild, on a staging copy.

How do I know which classic template file renders a page?

Use the template hierarchy: WordPress chooses the most specific matching file, such as single-product.php before single.php. To confirm, make a visible test change to the file you think is responsible and load the page.

Adding an internal link in WordPress takes about ten seconds: select the words, press Ctrl+K, pick the page. The link itself rarely goes wrong. The things around it do: a URL copied from the edit screen, a slug renamed last spring, an anchor with a capital letter in the wrong place, or a plugin warning that says the links you can see aren’t there.

This guide covers the editor steps, then the cases the editor doesn’t handle: section links, menus, WooCommerce products, and what to do when a link breaks. Internal links are one part of the wider job of doing SEO on WordPress. They are also the part that slowly goes stale on any site that keeps publishing.

What you need before you start

You need an account that can edit the post or page, and the destination has to be published. A link to a draft takes logged-out visitors to a 404. If the destination doesn’t exist yet, create and publish the page first, and settle its slug before anything links to it.

These steps are for the block editor. In the Classic Editor, the link button in the toolbar does the same job.

How do you add an internal link in the block editor?

1. Select the words that describe the destination. Choose “business audit checklist”, not “here”. The link should sit in the sentence where the reader would want the next step.
2. Open the link control. Press Ctrl+K (Cmd+K on a Mac) or click the link icon in the block toolbar.
3. Search or enter the destination. Type part of the post or page title and WordPress searches your own content. Pick the correct result, and look twice when two titles are similar. You can also paste a full URL, a relative path like /about, or an anchor on the same page like #contact.
4. Leave the advanced options off. For an internal link, “Open in new tab” and nofollow should normally stay unticked.
5. Press Enter, then Save or Update the post.
6. Test it as a visitor. Open the published page in a private window and click the link.

Step six is the one people skip, and it is the one that catches mistakes. WordPress’s Link control documentation says the editor checks whether a URL is formatted acceptably. It does not check whether the page exists or loads. A typo in a slug looks fine in the editor and returns a 404 on the live site.

Why you should select words before pasting a URL

If you paste a bare URL on its own line, the editor may turn it into an embed or a preview card instead of a text link. WordPress’s documentation warns about this. Select the words first, then add the link to them.

Why you should never link to an admin URL

A URL copied from the address bar while you are editing looks like /wp-admin/post.php?post=123&action=edit. It works for you because you are logged in. For everyone else it goes to a login screen. A thread on WordPress.org’s support forums turns on exactly this mistake. Open the page itself in a private window and copy that address.

Match the exact version your site serves. If your site uses https://www.example.com/pricing/, a link to http://example.com/pricing still arrives, but only after one or two redirects. Visitors and crawlers both pay for each hop.

What does a correct internal link look like?

In the page source, a correct internal link is a plain anchor element with an href, descriptive text and no extra attributes:

<a href="https://www.example.com/services/business-audit/">business audit service</a>

Google’s link best practices page says Google uses links to find new pages to crawl and as a signal of relevance, and asks for crawlable links with descriptive anchor text. Accessibility asks for the same thing. WCAG 2.2 success criterion 2.4.4, Level A, requires that a link’s purpose be clear from its text or the text around it. “Click here” fails, and so does an empty link around an icon.

Don’t add nofollow to internal links. WordPress describes nofollow as telling search engines not to associate with or crawl the linked page from your site. That is almost never what you want for your own pages. It also doesn’t fix a broken link or remove a page from search.

How do you link to a section of a page?

You give the section an HTML anchor, then link to it with a hash.

1. Select the heading (or other block) you want to jump to.
2. In the block settings sidebar, open Advanced and type a name in HTML Anchor, for example pricing-faq.
3. Link to #pricing-faq from the same page, or to https://www.example.com/pricing/#pricing-faq from another page.

WordPress’s Page Jumps documentation sets the rules: anchors are case-sensitive, contain no spaces, start with a letter and must be unique on the page. If clicking a jump link takes the reader to the top of the page instead of the section, the anchor and the link don’t match exactly. #Pricing-FAQ and #pricing-faq are different anchors.

Where are menu and WooCommerce product links set?

Menus are a separate system

A link inside a post never becomes a menu item, and a menu item doesn’t count as a link in your article. In a block theme, edit menus in the Navigation block (Appearance, then Editor, then Navigation) and add a page link or a Custom Link. Classic themes use Appearance, then Menus. Both kinds of link matter, but only contextual links in the body tell readers and search engines which specific pages relate to this one.

WooCommerce has three kinds of product link

To link to a product inside a post, use an ordinary link to the product’s public URL. Recommendations work differently. WooCommerce’s documentation explains that you choose up-sells and cross-sells by hand in the product’s Product data panel, under Linked Products. WooCommerce generates related products automatically from shared categories and tags, so you can’t pick them one by one. Whether these lists appear, and where, depends on your theme.

Product URLs follow the product permalink setting under Settings, then Permalinks. If you change it on an established store, every product link typed into posts points at the old structure. Add redirects and update those links in the same session.

Which pages should you link, and how many links?

There is no correct number. Guides recommend anything from two links per post to one every 50 words, and none of those figures comes from a controlled test. Two rules hold up better: link where the reader would want to go next, and make sure every page you care about has at least one link to it from the body of another page.

Many sites miss the second rule. In Ahrefs’ study of over a million domains, 66.2% of sites had at least one page with only one dofollow internal link pointing to it. Note that the figure is for sites, not pages. Still, under-linked pages are common.

A habit that scales well with a small archive:

• When you publish, link the new post to two or three older pages it builds on.
• Then open those older pages and link back to the new one where it adds something.
• Link from service, product or category pages only where the sentence supports it. A related offer at the right moment helps readers. A forced one reads like an ad.
• Once a quarter, use a crawler or your SEO plugin’s link report to find pages with no inbound links, and give each one a home.

Plugins that suggest or auto-insert links save search time on large archives. Practitioners regularly report irrelevant suggestions and repetitive anchors, and AI tools that make up URLs or break HTML. Treat every suggestion as a draft and read the sentence it lands in before you accept it.

Why does Yoast say there are no internal links when there are?

Yoast’s content analysis shows “Internal links: No internal links appear in this page, make sure to add some!” even on pages with several links. One WordPress.org support thread opens with exactly that complaint about a post with at least three links. The usual reason is where the links sit. Yoast reads the post content, so links in menus, footers, sidebars, some page builder modules and custom fields often aren’t counted. Yoast’s support has said search engines can still crawl those links.

So trust the page, not the counter. If you want the warning gone:

• Put at least one link in a normal paragraph in the editor, not in a builder module or custom field.
• Check that the Site Address under Settings, then General, matches your live URL, including https and www. A mismatch can make your own links look external.
• Run Yoast’s SEO data optimization from the Yoast SEO tools screen.

Yoast’s link suggestions in the editor are a Premium feature, and Yoast’s help page says to run the data optimization first. If you don’t see suggestions on the free version, nothing is broken.

What to do when an internal link doesn’t work

Find out what the destination returns, then match the fix to the cause.

• 404 after a slug change. Add a 301 redirect from the old URL to the new one, then update the links that still use the old path. A redirect is a safety net, not a replacement for correct links. A helpful custom 404 page catches the visitors you miss.
• 404 because the page was deleted. Redirect to a page that answers the same need. If none exists, remove the link.
• Every pretty URL returns 404. Open Settings, then Permalinks, and click Save Changes without changing anything. WordPress rebuilds its rewrite rules. This fixes rewrite problems only. It won’t fix a typo or a deleted page.
• The editor misbehaves. If the URL disappears after Ctrl+K, or nofollow gets added when you didn’t choose it, a theme or plugin is interfering. Run a conflict test, switching to a default theme, turning all plugins off and turning them back on one at a time, as described in our guide to plugins that stop working.
• Links point at the old domain after a migration. They may still work through redirects, but each one takes a detour. A database search-and-replace from the old domain to the new one fixes them all at once. Take a backup first. If the original domain is carrying over to the rebuilt site, keep linking to it rather than to the temporary staging address.

If you’d rather not do this cleanup page by page, SiteSelf takes it as a chat request: it updates the links, adds redirects and other SEO fixes on your site, and reports what changed and what it checked.

Stop and get help when links break across the whole site after a migration or host move, or when the editor fails the same way with every plugin off and a default theme on. At that point the cause is in the server, the database or WordPress itself, and it needs someone with hosting access.

Frequently asked questions

Should internal links open in a new tab?

Usually not. The reader is staying on your site, and a new tab breaks the back button they expect to use. If you do open a link in a new tab, W3C lists telling users in advance as an advisory technique, for example by adding “(opens in a new tab)” to the link text.

Should I use relative paths or full URLs?

Both work in a browser, and the link control accepts paths like /about. Full URLs are easier to search and replace after a domain change and behave the same in feeds and emails. Whichever you use, use it consistently.

How do I edit or remove a link?

Click the linked text in the editor. A small popover shows the destination with buttons to edit it or remove the link. Removing the link keeps the words. Then update the post.

Do internal links improve rankings?

They help search engines find pages and understand which pages relate to each other, and Google says it uses them as a relevance signal. No public controlled study shows that adding a set number of links lifts a given page. Reports of traffic gains after linking work usually come with other changes made at the same time.

Does every WooCommerce product need links from other products?

No. Store owners disagree about product-to-product linking, and linking every product to every other one looks spammy to shoppers. Relevant links from guides and category pages, plus up-sells and cross-sells chosen with care, do the job.

Can I change the same link across many posts at once?

Core WordPress has no bulk link editor. On a small site, search your posts for the old URL and edit each result. On a large one, a database search-and-replace is faster, but take a backup and test a single post first.

A contact page with a grey box where the map should be, or a darkened map stamped “For development purposes only”, tells every visitor that nobody is looking after the site. It’s also one of the easiest things on a WordPress site to get wrong. “Map widget” can mean five different things, and they each have their own settings.

Here is what those five are, which one fits your page, how to add each, and how to find out why a map won’t load. If you’re still building the page the map will sit on, start with how to add pages in WordPress.

Which kind of map does your page actually need?

Start with the job, not the plugin. A single office address needs something much simpler than a dealer network with a radius search, and the simpler option has fewer ways to break.

What you need	Simplest approach	Google API key?
One location on a contact page	Google Maps share-link iframe in a Custom HTML block	No
A map in a sidebar or footer	Custom HTML block in the widget area, or a plugin’s widget	Only for plugin widgets that use Google
Several markers, popups, categories	A map plugin with a block, widget and shortcode	Yes with the Google engine, no with OpenStreetMap or Leaflet
Store locator, radius search, filters	A store locator plugin or a full map plugin’s locator	Usually, for address search
A map built from your own data (listings, custom fields)	Custom code, often with Leaflet	Depends on the tile provider

Page builders have map widgets of their own. Elementor, for example, documents its own Google Maps integration, which has nothing to do with any map plugin. A key you save in one product does nothing for another. The most common mistake with these maps is pasting a key into the wrong plugin.

Before you build a store locator, check that visitors will actually use a map. On many local business sites people only want the address, a phone number and a directions link. Those do more for them than an interactive map.

How to add a single-location map without a plugin

For one address, the embed code from Google Maps is the most reliable option. You don’t create an API key, set up a Cloud project or install a plugin to keep updated.

1. Open Google Maps, search for your business or address, and click Share.
2. Choose the Embed a map tab, pick a size, and click Copy HTML.
3. In WordPress, edit the page, add a Custom HTML block where the map should go, and paste the code.
4. Add a title attribute to the iframe that says what the map shows.
5. Below the map, type the full address as normal text in a Paragraph block.
6. Update the page, then load it in a private browser window to check the map renders.

The finished code should look like this. The src value will be longer:

<iframe src="https://www.google.com/maps/embed?pb=..."
  title="Map showing Example Bakery, 12 High Street, Leeds"
  width="600" height="450" loading="lazy"></iframe>

The address text in step 5 matters more than people think. The W3C’s accessibility technique H64 uses the iframe title to name the frame. A screen reader user learns there is a map, but can’t read the street name from it. Search engines index your page text, not the map tiles. So put the address, phone number and opening hours in text, and add LocalBusiness structured data if you use an SEO plugin that supports it.

If you would rather not do this yourself, SiteSelf can add the embed and the address text to your WordPress pages through chat, then fetch the live page and report what changed. Pages owned by Elementor, Divi or Beaver Builder are refused, and the Google account side stays with you.

How to put a map in a sidebar or footer widget area

This depends on your theme. Go to Appearance. If you see Widgets, your theme has widget areas. If you only see Editor, you have a block theme, and the sidebar and footer are template parts you edit in the Site Editor. Our guide to editing the footer in WordPress explains both paths.

Both paths accept a Custom HTML block, so the iframe method above works there too. Keep the map small. A 300-pixel-wide map in a sidebar is enough to show where you are, with a “Get directions” link under it.

If you want the plugin whose name matches the search, Maps Widget for Google Maps, know one thing first. It shows a static thumbnail and opens the interactive map in a lightbox when clicked, and it was built for the classic widgets screen. The plugin’s support forum says it does not work with the block-based widget editor. It recommends installing the official Classic Widgets plugin or switching to a map block. If you manage many sites, that choice will come up again and again.

How to set up a Google Maps API key for a plugin

Plugins that load Google’s interactive maps need a key from Google Maps Platform. The steps below cover most of them. Always follow your plugin’s list of required APIs, because each plugin needs different ones.

1. Create or pick a Google Cloud project. For a client site, the client should own the project and its billing account and add you as a user. The charges belong to them, and so does the account.
2. Attach a billing account to that same project. Billing attached to a different project doesn’t count.
3. Enable the APIs your plugin lists. Interactive maps use the Maps JavaScript API, thumbnail images use the Maps Static API, and address search uses Places and Geocoding. Enable only what the plugin needs.
4. Create the key and restrict it. Under application restrictions, choose websites (HTTP referrers). Google’s security guidance reserves IP restrictions for server-side calls. Under API restrictions, allow only the APIs from step 3.
5. List every hostname the site uses. For example https://example.com/*, https://www.example.com/* and https://staging.example.com/*. A wildcard such as *.example.com/* covers subdomains but not the bare domain, so add both.
6. Paste the key into that plugin’s own settings field. If the plugin has a “Test API Key” button, use it.
7. Wait before you test. GravityKit’s referrer error guide says restriction changes can take up to five minutes to apply. If you change three settings in two minutes, you won’t know which one fixed it.

If you loosen a restriction to test, put it back afterwards. A browser key with no restrictions can be copied from your page source and used on anyone’s site, and your billing account pays for it.

What a Google-powered map costs

For most small sites, nothing. You still have to add billing details. Google’s March 2025 pricing change replaced the old $200 monthly credit with a free monthly usage threshold for each SKU, from March 1, 2025. Guides written before then that mention the credit are out of date.

Google’s Maps Embed API billing page says that API is free for unlimited requests, but it still needs a key and a billing account. The Maps JavaScript, Static, Places and Geocoding APIs charge for usage above their free thresholds. Sites with many listings or address lookups on every page view are the ones that run up bills. Set a daily quota on each API in the Cloud console so a traffic spike stops the map rather than running up the bill.

If you don’t want to manage any of this, choose an engine that doesn’t use Google. WP Go Maps offers Google, Leaflet and OpenLayers engines. MapPress describes itself as “Free, no API key, no setup” and supports Leaflet, OpenStreetMap and Mapbox as well as Google. You give up Google’s familiar map style and some of its place data. In exchange there’s no key, no project and no bill.

Why a map shows blank, grey or watermarked

Open the page, press F12, and look at the Console tab. Google writes a named error there, and each name points to one setting. Google’s error messages reference lists them all. The table starts with the most common ones.

Console error	What is wrong	Fix
MissingKeyMapError, InvalidKeyMapError	No key, or the wrong key, in this plugin’s field	Paste the right key into the plugin that draws the map
BillingNotEnabledMapError	No billing on the project that owns the key	Attach billing to that project, not a different one
ApiNotActivatedMapError	The API the plugin calls is not enabled	Enable it in the key’s project
ApiTargetBlockedMapError	The key’s API restriction leaves that API out	Add the API to the key’s allowed list
RefererNotAllowedMapError	The page’s URL is not in the referrer list	Add the missing hostname (www, non-www, staging), then wait
OverQuotaMapError	A usage limit was reached	Wait for the daily reset or raise your own quota

A key that works on one domain and fails on another is almost always a referrer problem. Adding billing doesn’t fix a wrong key, and a correct key doesn’t turn on an API you haven’t enabled. Each is a separate setting.

If there’s no Google error, the problem is on the WordPress side. Check these in order:

• Cache. Purge your caching plugin, the host cache and any CDN. Then reload in a private window.
• Two loaders. A theme with built-in maps and a map plugin can both load Google’s script. Turn off the script loading in one of them. Don’t install a third plugin to fix the first two.
• Optimisation plugins. Settings that combine or delay JavaScript can break map scripts. Exclude the map script, or test with those settings off.
• Hidden containers. A map inside a tab or accordion can render at zero size. Your plugin’s docs will explain how to redraw it when the tab opens.
• Theme hooks. A custom theme that never calls wp_footer() in footer.php drops the scripts many plugins add at the bottom of the page.
• Thumbnail shows, click does nothing. On thumbnail-and-lightbox maps, this usually means another script has loaded the lightbox library twice, or an earlier JavaScript error stopped the page. It isn’t a key problem.
• Wrong location. The address was too vague. Use the full street, town and country, or enter coordinates. A new key won’t change the pin.

To test for a conflict on a live site, use the Health Check plugin’s troubleshooting mode. The WordPress support handbook explains that it turns off plugins and switches to a default theme for your logged-in session only. Visitors see the normal site. Then turn plugins back on one at a time. Our guide to fixing plugins that stop working covers that routine in detail.

When to stop and get help

Get a developer or your host involved if all three of these are true: the console shows no Google error, Health Check troubleshooting mode with every plugin off still shows a blank map, and the map works on a default theme but not on yours. The problem is then in the theme’s code. Get help too if you need the map to write to other systems, such as putting a selected pickup store’s address into a WooCommerce order. That needs custom code using the plugin’s hooks.

What to keep in mind after launch

A map plugin is code on your site like any other plugin, and map plugins have needed security fixes. Keep them updated, and delete any you’ve stopped using. An iframe embed has no plugin code to update, which is another reason it suits a single location.

Speed is the other ongoing cost. An interactive map loads Google’s script and map tiles from outside your site. Put it only on the pages that need it, and use lazy loading or the thumbnail-and-lightbox approach so the map doesn’t load until a visitor needs it.

Frequently asked questions

Do I need a Google Maps API key to show a map in WordPress?

Not for the share-link embed you copy from Google Maps and paste into a Custom HTML block. You do need one for plugins or builder widgets that load Google Maps Platform APIs. Plugins running OpenStreetMap or Leaflet engines don’t need a Google key.

Widget, block or shortcode: which should I use?

Use a block in page content, a block or widget in sidebars and footers, and a shortcode in places that accept neither, such as some builder text modules. Many map plugins offer all three. Check whether a widget was built for the classic widgets screen before you rely on it in a block theme.

Why does the map show “For development purposes only”?

Google adds that watermark when the key or billing fails its checks. The console usually names the reason, most often billing missing from the key’s project or an API that isn’t enabled. Fix that setting, wait a few minutes, and reload.

Who should own the Google account on a client site?

The client. They create the project, attach their own billing, and add the developer as a user. Charges then go to the business that uses the map, and access stays with the client if the developer moves on.

Can I show my customers’ locations on a map?

Mapping your own stores is different from mapping where buyers live. Showing customer addresses, even roughly, raises privacy questions. Check with whoever handles your privacy policy before you publish one.

You change the headline, click Update and reload the site, and the old headline is still there. On WordPress this rarely means the save failed. Usually you edited something other than what WordPress serves at the root of your domain.

“Edit the homepage” can mean three different jobs. You might be choosing which page WordPress shows at the root, editing that page’s content, or changing the template that lays it out. Each job happens on a different screen. Our guide to editing pages in WordPress covers the page editor in general. This article covers the homepage, which is where most of the traps are.

Find out what produces your homepage before you edit

You need three answers first, and they take about two minutes to get:

1. Settings > Reading. “Your homepage displays” is set to either Your latest posts or A static page. If it says static, write down which page is selected as the Homepage.
2. The Appearance menu. If it has an Editor item, your theme is a block theme. If it shows Customize and no Editor, your theme is a classic theme.
3. The live homepage, viewed while logged in. If the admin bar shows Edit with Elementor or another builder’s button, a page builder owns the layout.

Those answers tell you where to make the edit:

Your setup	Where to edit
Static page, block editor	Pages > All Pages, then the page named in Reading
Block theme with a Front Page template	Appearance > Editor > Templates > Front Page
Latest posts, block theme	Appearance > Editor, the Home or Index template
Classic theme	Appearance > Customize for the theme’s homepage options. If the theme has a front-page.php file, the layout lives in that file.
Page builder	The builder, opened from the live homepage

One habit prevents most problems. Open the live homepage and click Edit in the admin bar. You get the document WordPress is actually serving, not a duplicate with the same title.

How to choose which page is your homepage

WordPress.org’s guide to creating a static front page gives the steps:

1. Publish the page you want to use. The Homepage dropdown only lists published pages, and our guide to adding pages in WordPress explains why drafts and private pages are left out.
2. Go to Settings > Reading and select A static page.
3. Choose your page in the Homepage dropdown.
4. If you run a blog, you can also choose a Posts page. WordPress will not let the Posts page be the same page as the Homepage.
5. Click Save Changes.

Calling a page “Home” does not make it the homepage. Only this setting does. After you save, WordPress marks the page “Front Page” in your Pages list, which makes it easy to find next time.

Why the page you picked may not be what visitors see

A template can override the Reading setting. WordPress.org’s additional guide to the Site Editor says that in a block theme, a Front Page template takes precedence over the Reading setting. Classic themes have the same rule. The template hierarchy uses front-page.php for the front page whatever Reading says. The name home.php is misleading: it is the posts index, not the homepage.

Here is what that means in practice. Suppose Reading names your page, you edit it, you publish, and nothing changes. Open Appearance > Editor > Templates and look for a Front Page template. A template only shows a page’s own content if it contains a Post Content block. Without that block, your page edits have nowhere to appear. You have two options: add a Post Content block to the template so page edits show up, or edit the template itself.

How to edit a static homepage in the block editor

1. Go to Pages > All Pages and find the entry marked Front Page.
2. Click Edit. Change the text, images and buttons directly in the blocks. If a block is nested inside groups or columns, open List View to select it.
3. Click Save (called Update in older versions) and wait for it to finish before you leave the screen.
4. Open the homepage in a private window. The private window skips your logged-in view and your browser cache.

Colors and fonts that appear across the site belong in the Styles panel, not in each block’s settings. If you style blocks one by one, the next homepage change means redoing that work.

How to edit the homepage in a block theme’s Site Editor

If your site shows latest posts, or the theme ships a Front Page template, the homepage is a template, and it may not appear in your Pages list at all. WordPress’s own contributors acknowledge this. Gutenberg issue #56244 is about making the Home page easier to find in the editor.

1. Go to Appearance > Editor > Templates.
2. Open Front Page. If there is none, open Home, the template for the posts page. If neither exists, open Index, the fallback. Some themes use slightly different names.
3. Edit the blocks and click Save.

Pay attention to what you are editing. A change to the Front Page template only affects the root URL. The header and footer are template parts shared by every page, so editing them inside the homepage template changes them across the whole site. If a template edit goes wrong, the Site Editor keeps revisions and lets you reset a customized template to the theme’s default.

How to edit a classic theme homepage

Classic themes send you to Appearance > Customize. The Homepage Settings panel there mirrors the Reading setting. Many themes add their own panels for homepage sections, such as the hero, featured boxes and widget areas. If the theme has a front-page.php file, some of the layout is written in PHP and no setting will change it. That is a job for a child theme, and our guide to editing themes without losing work explains why you should never edit the parent theme’s files.

How to edit a homepage built with Elementor or another builder

Open the live homepage and click Edit with Elementor in the admin bar, then click Update when you are done. Starting from the live page matters. On one WordPress.org support thread, an Astra starter-template import had created two Home pages and two Elementor Default Kits. The owner kept editing the copy that was not live, and caching turned out not to be the cause. If you think you have duplicates, check which page Settings > Reading names before you delete anything.

Do not open a builder page in the block editor and rewrite it there, because that can break the builder’s layout data. Elementor’s History panel, at the bottom left of the editor, lists recent revisions if you need to step back.

You may see “Sorry, the content area was not found in your page. You must call the_content function in the current template.” Elementor’s help page on that error gives two causes. Either the template has no content area, or you are trying to edit a dynamic page such as an archive or a shop page. Use Theme Builder for dynamic pages. A template that is missing the_content needs a developer or a different theme.

Why your homepage changes are not showing

Check these in order. The cheap, common causes come first:

1. You edited the wrong document. Click Edit from the live page and compare. Confirm the status is Published, not Draft, Pending or Scheduled. Also confirm you are on the live domain and not a staging copy or a translated version.
2. A template controls the layout. See the Front Page and Post Content section above.
3. A cache is serving an old copy. There can be several layers: your browser, a cache plugin, your host’s cache and a CDN. Elementor sites have one more, the CSS files Elementor generates, which its changes-not-appearing guide tells you to clear at Elementor > Tools > Clear Files & Data. Purge each layer once. If a full purge changes nothing, the cache was not the problem, so stop purging and go back to step 1.
4. The editor will not load or save. Plugin conflicts, PHP memory limits and host firewalls cause this. Take a backup first (see what a backup plugin covers), then isolate the cause using our guide to fixing plugins that are not working.
5. It only looks wrong on mobile. Builders store separate settings for mobile. Check at phone width before you decide the desktop edit failed.

Three problems that look like homepage edits but are not

The WooCommerce Shop page. WooCommerce assigns its Shop page separately from your homepage. According to WooCommerce’s Product Catalog documentation, the layout of that page comes from the Product Catalog template in the Site Editor. Content you type into the Shop page may not appear.

Google still shows the old version. Search results are not your website. Google Search Central’s page on asking Google to recrawl says recrawling can take days to weeks. You can request it once with URL Inspection in Search Console. Requesting it repeatedly does not make it faster.

The homepage vanished after a theme switch. WordPress.com’s homepage troubleshooting guide notes that the old homepage can end up in Pages > Drafts. The same check works on any WordPress site: republish the page, then select it again in Settings > Reading.

When to stop and get help

Stop when the fix means editing front-page.php or adding the_content to a template. Stop when the error points to a host limit such as memory or a firewall rule, because only your host can change those. And stop before you delete pages or re-import a starter template to fix duplicates you have not identified yet. Doing that before you know which copy is live usually makes the damage worse.

Whoever helps you will want the same things: the URL, what Settings > Reading says, the theme, the builder, and the exact error text. If you would rather hand the change over, SiteSelf can make homepage and page edits through chat on request and tell you what it changed and checked, though it refuses pages owned by Elementor, Divi or Beaver Builder when the work starts.

Frequently asked questions

Can I edit my homepage by typing directly on the live site?

No. WordPress edits happen in the dashboard: the page editor, the Site Editor or your builder. The Edit link in the admin bar on the live page takes you to the right one.

Why can’t I find my homepage in Pages?

On a block theme that shows latest posts, or one with a Front Page template, the homepage is a template rather than a page. Look under Appearance > Editor > Templates.

How do I put my blog on its own page?

In Settings > Reading, choose A static page, pick your homepage, and pick a different page as the Posts page. Leave that Posts page empty, because WordPress replaces its content with your post list.

How do I change the homepage title that shows in search results?

SEO plugins set it in different places depending on your Reading setting. For a static homepage it is usually set on the page itself. For a latest-posts homepage it is in the plugin’s site-wide settings. Either way, Google shows the new title only after it recrawls the page.

Only my homepage breaks in Elementor. What else can I try?

People report success with a simple workaround: create a new page, copy the content across, and select the new page as the homepage in Reading. This is anecdotal. Afterwards, rename or delete the old copy so you do not create the duplicate-page problem.

Will editing the Front Page template change my other pages?

The template itself only applies to the root URL. The header and footer inside it are shared template parts, so editing those changes every page on the site.

The update button is the easy part. WordPress’s own Updates screen warns that any changes made to theme files will be lost, and that warning covers most of the damage people see afterward: a header gone, a mobile menu that stops opening, a custom template back to the theme author’s version. The site still loads, so nobody notices until a customer does.

This guide covers the dashboard update, the manual route, premium themes, what to check afterward, and how to read the error when an update fails.

Answer three questions before you click update

A theme update is low risk when nobody has edited the theme and the site is simple. It carries more risk when the theme has been customized, when it is a premium theme with a license, or when the site is a store. Three questions tell you which case you are in.

Where do your customizations live? If someone edited style.css, functions.php or a template file inside the parent theme, including through Appearance > Theme File Editor, the update overwrites those edits without warning you. Before you update, move them into a child theme (for PHP and templates), a small site-specific plugin (for code snippets) or Appearance > Customize > Additional CSS (for styling). Setting up a child theme does not move existing edits into it. You have to find each edit, copy it across and test it. Our guide to theme customization that survives updates covers where each kind of change belongs.

Where does this theme get its updates? Free themes from the WordPress.org directory update through the dashboard. Themes bought on the WooCommerce Marketplace update through the WooCommerce.com Update Manager. Other premium themes update through their vendor’s license, which is usually tied to one domain.

Can you get back? Take a backup of the database and the whole wp-content folder. WooCommerce’s update guide gives the same scope for a manual store backup. Then confirm you can actually restore it. A backup you have never restored is a guess.

For a store or a heavily customized site, run the update on a staging copy first. If your host offers one-click staging, use that. Otherwise a staging plugin will do the job.

How to update a theme from the dashboard

You need an administrator login. No hosting access is needed unless WordPress asks for FTP credentials, which is covered in the errors table below.

1. Go to Appearance > Themes. A theme with an update available shows a notice on its card. Click the card, then View details to read the changelog. Look for a major version jump, a new minimum PHP version or a new required plugin.
2. Take and confirm your backup.
3. Click Update now on the theme card. The other route is Dashboard > Updates: tick the theme under Themes, then click Update Themes.
4. Wait until the screen confirms the update is done. Closing the tab while it runs is how sites end up stuck in maintenance mode.
5. Clear every cache layer: your caching plugin, the host’s server cache, and any CDN. Then open the site in a private browser window.

You do not need to deactivate a child theme to update its parent. Leave the child theme active and update the parent.

Theme updates and plugin updates share most of their mechanics: the same Updates screen, the same maintenance file, the same permission failures and rollback tools. If you would rather not run this cycle yourself, SiteSelf handles WordPress plugin and theme updates on request through chat, and anything that touches theme files needs hosting access.

Premium themes follow the vendor’s channel

A premium theme that shows no update usually has a license or connection problem. The theme itself is rarely at fault. For WooCommerce Marketplace themes, WooCommerce’s troubleshooting page lists the usual causes: an expired subscription, the wrong or disconnected WooCommerce.com account, a key assigned to another site, a missing Update Manager, a blocked REST API (load yourdomain.com/wp-json/ and you should see JSON), Plain permalinks, WP-Cron not running, a firewall or security plugin, or restrictive file permissions.

Other vendors bind the license to a domain. After a migration, or on a staging copy, updates can fail with “Download failed. Unauthorized.” until you register the license again for the current URL.

Updating manually with a ZIP

The manual route is fine when the dashboard update is not offered, for example with a premium theme you downloaded from the vendor. Go to Appearance > Themes > Add New > Upload Theme and upload the ZIP. When WordPress recognizes the theme is already installed, choose Replace current with uploaded.

Three mistakes cause most manual failures. The first is uploading the vendor’s full package (theme plus documentation) instead of the installable theme ZIP, which returns “No valid themes found” or a missing style.css error. The second is extracting the ZIP first. The third is deleting the old theme before you upload, which WooCommerce’s theme update guide warns loses your customizations.

Uploading the theme folder over FTP into /wp-content/themes/ also works. Treat it as a workaround: if the dashboard update failed, the reason it failed is still there.

What a correct result looks like

A finished update shows the new version number on the theme’s card under Appearance > Themes. On the site itself, check the pages that earn money or leads, not just the homepage:

• Header, footer and menus, including the mobile menu at phone width.
• One post, one page, an archive and the 404 page.
• Every form, with a real test submission.
• Your browser console and the PHP error log, for new warnings.

Stores need more. WooCommerce’s update guide lists product pages, cart, checkout, payments, shipping, taxes and emails. Then open WooCommerce > Status > System Status and scroll to Templates. If your theme overrides WooCommerce templates and those copies are now outdated, they are flagged there. Update the override to match the current template, or remove or rename it so WooCommerce falls back to its default.

Some breakage stays invisible. In one project’s GitHub issue, an Avada site came through an update with “nothing visibly broken,” yet its pages grew to about 1.46 MB of raw HTML, up from about 0.3 MB. A quick page-weight or speed check after the update catches this kind of regression.

Should you turn on theme auto-updates?

WordPress lets you enable auto-updates per theme from Appearance > Themes. That makes sense for an unedited theme on a simple site with working backups. It makes less sense for a store, a site with template overrides or a page builder, or any site where a broken checkout costs revenue before anyone notices.

Professionals are split. In MelaPress’s 2025 survey of 264 professionals, 32% of web designers and 33% of web developers used automatic updates. Agencies commonly stage risky updates (page builders, WooCommerce, major versions), batch the low-risk ones and keep a 24 to 48 hour rollback window. Waiting forever carries its own risk: a site several major versions behind is much harder to bring up to date than one that has been updated regularly.

What to do when the update fails

Read the exact message before you retry anything. Each message points to a different cause.

What you see	Likely cause	Fix
“Could not create directory”, or WordPress asks for FTP details	File ownership or permissions on wp-content/themes and wp-content/upgrade, or a full disk	Ask your host to correct ownership and check disk space. Don’t open permissions across the whole site.
“There has been a critical error on this website.”	A PHP, plugin or page-builder conflict with the new version	Use the recovery-mode email link, read wp-content/debug.log, test on a default theme, then deactivate plugins one at a time.
No error, but custom layout or features are gone	Edits in the parent theme were overwritten	Restore the old theme files from backup, move the edits into a child theme, then update again.
“Download failed. Unauthorized.”	License expired or registered to another domain	Renew, or register the license again for this URL.
“Briefly unavailable for scheduled maintenance. Please check back in a minute.”	An interrupted update left a .maintenance file behind	Delete .maintenance from the WordPress root (not the theme folder), then run the update again.
“Destination folder already exists” or “No valid themes found”	Wrong ZIP, or the upload collided with the existing folder	Upload the installable ZIP and choose Replace current with uploaded.
Site looks unchanged, or oddly styled	Cache	Purge the plugin, server and CDN caches, then check in a private window.

Deleting .maintenance brings the site back but does not finish the update. Confirm the version number afterward. For a white screen or critical error, our guide to fixing a WordPress white screen walks through the isolation steps.

Stop and get help when the error log names the theme and you cannot tell what changed, when a restore fails, or when checkout is affected on a live store. Stacking more changes on top of a failure you don’t understand makes the cause harder to find.

How to roll back a theme update

Since WordPress 6.3, if a manual theme update fails partway through, WordPress restores the previous version, which it keeps temporarily in wp-content/upgrade-temp-backup/themes/. That covers a broken install. It does nothing when the update installs cleanly and the new version is the problem.

For that case you have two options. WP Rollback reverts any theme from the WordPress.org directory to an earlier version. It does not cover premium themes. For everything else, restore the backup you took before updating. Once the site is back, reproduce the problem on staging and fix the cause before you try the update again.

Frequently asked questions

Will updating my theme delete my posts and pages?

No. Posts, pages and media are stored in the database and uploads folder, not in the theme. The update puts code edits inside the theme’s folder at risk, and it can change how the site looks. Customizer settings are stored separately from theme files.

Do I need to update my child theme when the parent updates?

Not if it only holds small CSS or function tweaks. If it contains copied template files, or code that depends on the parent’s class names, compare those files against the new parent after a major release. The ColorMag threads on wordpress.org show child-theme sites breaking after a major update that changed classes.

Why did I lose customizations even though a child theme was active?

The edits were never moved into the child theme. Creating and activating a child theme does not copy anything across from the parent. Restore the old parent files from backup, find the edits, and move them over by hand.

Should I update core, plugins or the theme first?

People disagree, and there is no official order. What matters more is updating risky items one at a time (the theme’s major releases, page builders, WooCommerce), so a failure points to one cause. Batch the low-risk updates.

How do I stage a store update without losing new orders?

Don’t push the staging database back to live, because orders keep arriving on production while you test. Test the update set on staging, then apply the same updates on production and run your checkout checks there.

A WordPress.org forum poster once described 39 indexed pages, every one green in Yoast, a submitted sitemap and search engines allowed, and still nothing showed up in search. That thread sums up the whole topic. The settings were correct, and correct settings only get your site considered. Being considered and being found are separate problems.

Doing SEO on WordPress means three jobs. Get a handful of technical foundations right. Confirm they took effect on the live site. Then do the ongoing work of publishing useful pages and linking them together. The first two take an afternoon. The third never ends, and it is where the results come from.

What WordPress handles, and what stays your job

Out of the box, WordPress core gives you a search visibility setting, a permalink setting and an automatic XML sitemap at /wp-sitemap.xml. An SEO plugin such as Yoast SEO, Rank Math or All in One SEO adds control over per-page titles, meta descriptions, canonical URLs and structured data. No plugin has been shown to rank a site better than another, so pick on workflow and price.

What no plugin does is decide whether two pages compete for the same search, whether a page answers the question better than the pages already ranking, or whether anyone can reach it through your menus. Those decisions stay with you. If you are adding pages as you go, the basics of publishing pages Google can find apply to every one of them.

What you need before you start

• Administrator access to wp-admin. Every setting below lives under Settings or in the SEO plugin’s menu.
• A verified Google Search Console property for the live domain. It is the only place Google tells you how it sees your pages.
• A backup before you change permalinks, switch plugins or edit theme files.
• Optional: a terminal or your host’s file manager for the header checks and any theme fixes.

The setup, in the order that matters

1. Make sure the live site can be indexed at all

Go to Settings > Reading and find “Discourage search engines from indexing this site.” When it is ticked, WordPress adds a noindex, nofollow robots meta tag to every page. Visitors still see the site normally, which is why the setting survives unnoticed after launch. Untick it and save.

Then check two things the checkbox does not control. First, some hosts noindex staging sites with an X-Robots-Tag HTTP header as well as the WordPress setting. Kinsta’s documentation describes exactly this for its staging environments. If staging configuration was copied to production, the header can remain after you untick the box. Second, look at individual pages. Your SEO plugin can set noindex per page, per post type or for whole archives.

Do not use robots.txt to keep pages out of Google. Google’s noindex documentation is explicit: Google has to crawl a page to see its noindex tag. If robots.txt blocks the URL, Google never reads the tag, and the page can still appear in results.

2. Set permalinks once and redirect if you ever change them

On a new site, go to Settings > Permalinks and choose Post name, so URLs read /pricing/ rather than /?p=123. WooCommerce stores have a separate “Product permalinks” section on the same screen. WooCommerce’s documentation recommends short structures with relevant words, and warns that a custom product base can conflict with a taxonomy base.

On an established site, “switch to Post name” is not automatic advice. Changing the structure changes every existing URL, and old links from Google, email and social posts start returning 404s. If you must change it, map each old URL to its new one with a 301 redirect first. Google treats redirects as a strong signal of which URL you prefer.

3. Install one SEO plugin and use one sitemap

Pick one plugin and deactivate any other plugin that writes titles, meta descriptions, Open Graph tags or schema. Two plugins doing the same job produce duplicate tags. Yoast’s own help pages warn about Open Graph conflicts for exactly this reason.

Most SEO plugins replace the core sitemap with their own. That is fine, as long as only one exists. In Yoast, the switch is under Yoast SEO > Settings > Site features > XML sitemaps, and content types you set to stay out of search are left out of the sitemap automatically. Yoast also advises deleting any physical sitemap.xml file left in the site root by an old plugin, because it can shadow the real one.

A sitemap helps Google discover URLs. Google’s sitemap documentation says it does not guarantee crawling or indexing. A page that appears only in the sitemap, with no links from your menus or other pages, is still close to invisible.

4. Write a real title and description for each important page

Use the plugin’s fields under the editor, or set templates for whole post types. Each title should say what the page is, specifically: “Emergency plumbing in Leeds, same-day callouts” beats “Home | Services | Company Name.” Avoid template text repeated across dozens of pages.

Set expectations accordingly. Google can rewrite title links, and its snippet documentation says the result text comes mainly from page content and only sometimes from the meta description. Write the description anyway, because it is the version you control, but do not spend hours on it.

5. Pick one version of every URL

The same page can exist at http and https, with and without www, with and without a trailing slash, and with tracking parameters. Choose the preferred form, redirect the others to it, and keep internal links and sitemap entries consistent with it. Your SEO plugin outputs a self-referencing canonical tag on each page by default. Leave that alone unless you have a reason.

Manual canonicals are where this goes wrong. In one WordPress.org support thread, a Yoast post sitemap showed “This XML Sitemap contains 0 URLs.” Cache purges, a Cloudflare purge, disabling plugins and switching themes did nothing. The cause was hand-entered canonical URLs without trailing slashes on a site that used them. Removing them fixed it.

6. Validate structured data, and expect eligibility only

Your SEO plugin, WooCommerce or your theme outputs schema for articles, products and breadcrumbs. Run key pages through Google’s Rich Results Test, then URL Inspection in Search Console. Valid markup makes a page eligible for richer results. It does not guarantee them and it is not a ranking boost.

Theme code causes duplicates as often as plugins do. In a GeneratePress forum case, breadcrumbs loaded twice and Search Console reported “Missing field ‘item’ (in ‘itemListElement’).” The cause was a child theme’s header.php calling wp_head() twice, so every plugin’s head output appeared twice.

7. Measure speed with field data before you change anything

Google’s Core Web Vitals thresholds for a good experience are Largest Contentful Paint within 2.5 seconds, Interaction to Next Paint under 200 milliseconds and Cumulative Layout Shift under 0.1. Google uses them in its ranking systems, and its page experience documentation also says good scores do not guarantee top rankings.

WordPress sites are improving here. HTTP Archive’s 2024 Web Almanac found that the share of WordPress mobile sites passing all three metrics rose from 28% in 2023 to 40% in 2024. Check your own field data in Search Console’s Core Web Vitals report, find the failing template, and fix the specific cause: usually an oversized hero image, a heavy builder section or unneeded scripts. Adding a third optimization plugin on top of two others makes debugging harder and rarely helps.

8. Connect Search Console and submit the sitemap

Submitting the sitemap in Search Console is optional, and it is worth doing because you then get a report of what Google fetched. Use URL Inspection on your homepage and two or three key pages. It shows whether Google can crawl the page, which canonical Google chose, and whether a noindex was found.

How to confirm the settings actually reached the live site

A plugin’s “Settings saved” message tells you what is in the database. It does not tell you what the site serves. Caching, host rules, security plugins and theme code all sit between the two. Check the output directly, logged out, after clearing your cache:

# Any robots header added by the server or host
curl -sI https://example.com/ | grep -i x-robots-tag

# The robots meta tag and canonical in the served HTML
curl -s https://example.com/ | grep -iE 'name="robots"|rel="canonical"'

# What robots.txt really says
curl -s https://example.com/robots.txt

No terminal? Open the page, choose View Page Source, and search for robots and canonical. Then open /robots.txt and your sitemap URL in a private window.

A correct result: no noindex anywhere on pages you want found, one canonical tag per page pointing at the URL you chose, one title tag, one set of Open Graph tags, a robots.txt that does not disallow those pages, and a sitemap that lists real URLs in the same format as your canonicals. Repeat this after every plugin update, theme change or migration. Updates occasionally change defaults, and nothing on screen tells you when they do.

What to do if Google still is not showing your pages

Read the exact status in Search Console’s Pages report, because each one points somewhere different.

• “Excluded by ‘noindex’ tag.” A technical block. Find where the noindex comes from: the Reading setting, a page-level plugin setting, an archive default or a host header. Remove it, then request indexing.
• Sitemap “Couldn’t fetch.” Open the sitemap yourself. Common causes are Plain permalinks (one forum poster fixed a sitemap 404 by switching to Post name), two sitemap sources, a stale physical file, or a security rule blocking Googlebot.
• “Crawled – currently not indexed.” Usually not a setting. Google fetched the page and decided it was not worth indexing yet. Resubmitting the sitemap will not change that. Make the page more distinct and more useful, and link to it from pages Google already values.

If a plugin misbehaves in a way you cannot explain, test for conflicts one plugin at a time on a staging copy. The steps for isolating a plugin that is not working apply here too.

The part that moves rankings: pages worth finding

Google’s guidance on helpful content says its systems favour reliable, people-first content, written from first-hand knowledge. In practice that means one page per real question, answered better than the pages already ranking, with headings a reader can scan.

Practitioners on X and Reddit repeat one method so often it is worth trying, though nobody has controlled data for it. In Search Console’s Performance report, filter for queries where you sit around positions 4 to 20 and sort by impressions. Those pages are already close. Answer the query more fully, fix a weak title, and add internal links from related pages. That usually beats writing another near-duplicate post.

Three smaller habits help. Write alt text that describes informative images, and use alt="" for decorative ones, as the W3C images tutorial recommends, rather than stuffing keywords. Keep tags and categories purposeful, because a tag per post creates hundreds of thin archive pages. And do not noindex every archive by default either, because older posts can lose their only crawl path.

Give it time. Forum replies to owners with correct setups say competitive searches can take months. The r/marketing commenters in the research put it at three to six months before anything shows. Measure impressions and clicks in Search Console, not the plugin’s score.

When to stop and get help

Get a developer or your host involved when a noindex or X-Robots-Tag header persists after you have removed every setting you can find, when duplicate tags come from theme files, when a migration or domain change needs a redirect map, or when a security plugin or firewall is returning 403 errors to the SEO plugin. Those are code, server and hosting problems, not settings. If what you want off your plate is the routine part (titles, descriptions, redirects, plugin settings), SiteSelf handles WordPress SEO changes from chat: it works through its connector plugin for settings and content and needs hosting access for header or theme fixes, then fetches the changed page and reports what it found.

Frequently asked questions

Can I do SEO on WordPress without a plugin?

Partly. The visibility setting, permalinks and the core sitemap at /wp-sitemap.xml are free and built in. Per-page titles, meta descriptions and canonical control normally come from a plugin, and the free versions of the major ones cover those basics.

Which SEO plugin is best?

No evidence shows one plugin ranks sites better than another. Choose on interface, the features you actually use and licensing cost across your sites. Whichever you pick, run only one.

Does a green plugin score mean I will rank?

No. The score checks things like keyword placement and length on one page. It knows nothing about competing pages, links or whether your content answers the search better than what already ranks.

Do I need to submit my sitemap to Google?

No, Google can find it through robots.txt and links. Submitting it in Search Console is still worth doing, because you get a report on whether Google could fetch it and how many URLs it read.

Should I change my permalinks to Post name on an old site?

Only if the current structure causes a real problem, and only with 301 redirects from every old URL. Otherwise you trade a cosmetic improvement for broken links and lost signals.

How is WooCommerce SEO different?

Product permalinks have their own settings, product schema comes from WooCommerce or your SEO plugin and needs validating, and near-identical product descriptions compete with each other. Filling in every metadata field is not enough on its own. Distinct product pages and guides that link to them do more.