/7 min read

Moving a Small Site from WordPress to Astro

For a brochure site or a portfolio, leaving WordPress is mostly a weekend of content and a careful list of redirects. Here is when it is worth it, when it is not, and how to keep the rankings you already have.

ASTROWORDPRESSSEOGUIDE

Plenty of small sites end up on WordPress by default, not by decision. Someone set it up years ago, a page builder went on top, then a backup plugin, a security plugin, a cache plugin and a forms plugin. Now the site is slow, the update screen is a list of things nobody wants to click, and the client changes the content about twice a year.

That is the site this post is about. Not a newsroom, not a shop: a studio, a practice, a portfolio, a small business with a blog that gets a post every few months. For those, moving to Astro is very doable. The hard part is not the code. It is not losing what the old site already earned in search.

When it is worth it

The migration pays off when most of these are true:

  • The content barely changes. A handful of pages, some projects, a blog that gets a post now and then. Nobody logs into the dashboard every week.
  • The plugins are doing site work, not business work. Caching, image optimization, SEO meta, security hardening, a contact form. Astro does the first four at build time, and the form is one small route.
  • Speed and upkeep are the complaint. A page builder shipping a megabyte of scripts for a page of text, or a client who calls every time an update breaks the layout.
  • You are the one who maintains it anyway. If every content change already goes through you, a dashboard the client never opens is just one more thing to keep patched.

A prerendered Astro site has nothing to update on the server, no database to back up and no login page to attack. For a site like that, that is most of the value.

When to stay on WordPress

Be honest about these, because a migration that removes something the client relies on is a downgrade, however fast it is:

  • The client edits content themselves, often. If they publish weekly from the dashboard and like it, taking that away is a real cost. You can add a CMS on top of Astro, but that is a project of its own, not a detail.
  • WooCommerce, memberships or bookings. Those plugins are the business. Rebuilding them is not a migration, it is a new product.
  • Several editors, roles and drafts. Editorial workflow is what WordPress is good at.
  • Hundreds of posts with years of comments. It can be moved, but the effort grows with the archive, and the comments rarely come along cleanly.

There is a middle path, keeping WordPress as a headless CMS and building the front end in Astro. It works, but now you maintain both. For a small site, it is usually the worst of both worlds.

Before you touch anything: list every URL

This is the step that decides whether the migration costs you traffic. Before building anything, get a complete list of the URLs the current site serves, and especially the ones that get visits.

Three sources, combined:

  1. The sitemap. If an SEO plugin is installed, it is usually at /sitemap_index.xml or /sitemap.xml. It covers pages, posts, categories and tags.
  2. Search Console. The Performance report shows which pages actually get clicks and impressions. Those are the URLs you cannot afford to break.
  3. A crawl. Any site crawler will find what the sitemap missed: attachment pages, old landing pages, ?p=123 links still floating around.

Put them in a spreadsheet with one column for the old URL and one for where it will live on the new site. Every row needs an answer: same URL, a redirect to a new one, or gone on purpose.

Move the content

WordPress can export everything from Tools → Export as a single XML file. Open-source converters such as wordpress-export-to-markdown turn that file into one Markdown file per post, with frontmatter for title, date and categories, and download the images next to them.

What comes out is a starting point, not a finished result:

  • Page builder content does not survive. Posts written in the classic editor or blocks convert well. Pages built with Elementor, Divi or similar come out as a pile of shortcodes or nothing at all. Rebuild those pages as components and paste the copy in.
  • Shortcodes need a decision each. A gallery shortcode becomes a component or a list of images. A plugin shortcode that rendered a form or a slider usually just goes.
  • Images get duplicated. WordPress stores several sizes of every upload. Keep the original, let Astro generate the sizes at build time with astro:assets, and drop the rest.
  • SEO titles and descriptions live in the plugin, not the post. If the client wrote custom meta titles in Yoast or Rank Math, they are in the export as post meta. Copy them into each file’s frontmatter, or you lose the snippets that already rank.

On a typed content collection, the build will tell you which converted files are missing a field. Let it do the checking instead of reading every file.

Keep the URLs, or redirect them

This is the part that protects the rankings. A page that changes address without a redirect starts from zero.

The simplest option is not to change the URLs at all. If WordPress served posts at /my-post/, make the blog route generate /my-post/ too, or put them under /blog/ and redirect. Either is fine; mixing both by accident is what hurts.

Watch for these patterns:

WordPress URL What to do
/2024/05/post-name/ (date permalinks) Redirect to the new post URL, one rule per post or a pattern rule if the host supports it
/category/news/, /tag/design/ Redirect to the blog index or a matching category page, or let them go if they never got traffic
/?p=123, /?page_id=45 Redirect the ones that show up in Search Console; the rest are rarely worth it
/wp-content/uploads/... Keep the image paths if images rank in image search, otherwise redirect the important ones
/feed/ Redirect to the new RSS feed so existing subscribers keep receiving posts
/wp-admin/, /wp-login.php Let them return 404; there is nothing to log into anymore

Astro has a redirects option in the config. With an adapter for Vercel or Netlify, those become real redirects on the host. On a purely static build, Astro writes a small HTML page with a meta refresh instead, which search engines handle less reliably. For permanent moves, a host-level 301 is what you want: vercel.json on Vercel, a _redirects file on Netlify and Cloudflare. See where to host an Astro site for how the three differ.

One more detail: WordPress serves URLs with a trailing slash. Keep that consistent on the new site, so /about and /about/ do not compete as two separate pages.

The things plugins were quietly doing

When the plugins go, their jobs do not. Make sure each one has a new owner:

  1. Contact form. The forms plugin is replaced by a form route that validates and sends email. Test it from the production domain, not just the preview.
  2. Sitemap and robots. Astro’s sitemap integration generates the sitemap from the pages that actually exist. Submit the new one in Search Console on launch day.
  3. Canonical tags and social cards. The SEO plugin used to write them. Now the layout does, from the site URL in the config, so set that URL before you launch.
  4. Analytics. If the old tracking script was injected by a plugin, it disappears with it. Add it to the layout or switch to something lighter, but do not launch blind.
  5. Comments. Usually the right call on a small site is to drop them, keep the old ones as static text if they matter, and point people to email.

Launch day

Do the switch in one go, and check it the same day:

  1. Point the domain at the new host and confirm the redirect from www to the bare domain, or the other way around, still works.
  2. Go through the URL spreadsheet and open every row that had traffic. Each one should land on a real page, not a 404 and not the home page.
  3. Submit the new sitemap in Search Console.
  4. Keep the old WordPress install and its database backed up for a few weeks. You will not need it, until you need one image or one post nobody remembered.

Then watch Search Console for two or three weeks. A dip of a few days while Google re-crawls is normal. A growing list of 404s means a redirect is missing, and the report tells you which one.

The short version

Move a small WordPress site to Astro when the content changes rarely, the plugins are doing site work rather than business work, and you are the one maintaining it anyway. Stay on WordPress when the client publishes from the dashboard every week, or when a plugin like WooCommerce is the business. Either way, the migration lives or dies on one list: every old URL, and where it goes now.

If you want the new site to have the structure a WordPress site usually needs — pages, projects, a blog with RSS and sitemap, a working contact form — the templates in the Blog category ship with all of it, so the weekend goes into moving content instead of building a blog engine.

Try any demo before you decide

The demos are the real templates, deployed. No signup, no email in the way.