WordPress to Astro Migration Brief

The job is to move mobilebillboardsf.com off WordPress and onto a static Astro site hosted on Cloudflare Pages, deploying from GitHub. This is the exact process we used for mobilefoodexperts.com, and every other Boki business site runs the same stack.

Use it two ways: as the standard a candidate should be able to describe and reproduce, and as the source for the interview questions and the practical test in sections 6 and 7.

1. The site being moved

What a crawl of mobilebillboardsf.com shows today. Hand this inventory to the candidate as part of the practical test, then check whether they find anything it misses.

Every URL that has to map somewhere

Thirteen pages and four posts. All of these need either a rebuilt page or a 301 in the redirects file. Posts sit at the root with no /blog/ prefix, which is worth keeping so no post URL changes.

2. The target stack

A candidate should recognise every row here and be able to explain why each piece is there. This is what "done" looks like for us.

3. The migration process

These are the phases in the order we ran them. The order matters: SEO foundations and tracking go in before launch, and the redirects go live the same minute the DNS switches.

1. Export and inventory the WordPress site

   • Tools → Export → All content. This produces one WXR XML file. Ours was 1 MB, dated the day before the first Astro commit.
   • Download the media library, or at minimum every image actually used on a page.
   • Pull the full URL list from two places: the WordPress sitemap and Google Search Console's pages report. GSC catches junk URLs that still get impressions, such as /home-7891-6896 and /book-an-appoinment-7238, which a sitemap will not show.
   • Note every form, booking widget, tracking script and third-party embed on the old site. These are the things that silently break in a migration.
2. Plan the new site before writing code

   • Brand foundation: colours, heading and body fonts, a transparent-background logo at 600px or wider.
   • Page map with a meta title under 60 characters and an H1 for every page.
   • CTA hierarchy: the one action a visitor should take, then the second.
   • A URL mapping table, old slug to new slug. This becomes the redirects file later.
3. Set up the environment and the repo

   • Node LTS, Git, a GitHub account with access to the org.
   • npm create astro@latest, then add @astrojs/sitemap and sharp for image processing.
   • Commit early. Our first commit was the scaffold, the second was the gitignore. Never commit node_modules or dist. The MFE repo had to fix that on day three.

   // astro.config.mjs — the three settings that are not optional
   export default defineConfig({
     output: 'static',
     site: 'https://yourdomain.com',
     trailingSlash: 'always',
     integrations: [sitemap()],
   });

4. Build the layout and rebuild the pages

   • One BaseLayout.astro owns the head: charset, viewport, description, dynamic canonical from Astro.url.pathname, Open Graph, Twitter card, favicons, webmanifest, preconnects, fonts loaded with link tags and an async onload pattern, never @import.
   • Header and Footer as components. Footer carries the address as a Google Maps link, phone, email and social icons.
   • Pages rebuilt one at a time from the WordPress content. Copy is cleaned, not pasted with WordPress markup and inline styles.
   • Every image converted to WebP at 80% quality, with explicit width and height. Hero and logo load eagerly with fetchpriority="high", everything else lazy.
   • A branded 404 page. Skip-to-content link and ARIA on the mobile menu toggle.
5. Lay the SEO foundation

   • robots.txt allows everything, blocks the old /wp-content/, /wp-admin/, /wp-includes/, /wp-login.php and /xmlrpc.php paths, explicitly allows GPTBot, ClaudeBot, Google-Extended, CCBot and anthropic-ai, and points at sitemap-index.xml.
   • JSON-LD on every page: LocalBusiness or ProfessionalService, Organization with all social profiles in sameAs, BreadcrumbList. Page-specific: FAQPage, Article, CollectionPage, ContactPage, Person, WebApplication for calculators.
   • public/llms.txt listing every page and article URL.
   • Hard limits: meta title 60, OG title 60, Twitter title 55, Twitter description 125, meta description 160. No "Brand | Brand" duplicate in titles.
6. Install tracking

   • GTM container snippet in the head, noscript iframe right after the body opens.
   • GA4 configured as a Google Tag inside GTM with an all-pages trigger, then published.
   • Meta Pixel and Microsoft Clarity pasted directly into BaseLayout, not routed through GTM.
   • Verify in GA4 realtime and Meta Events Manager before launch, not after.
7. Write the security headers

   A single public/_headers file. The CSP has to allow every third party the site actually loads: Google Tag Manager, Google Analytics, Facebook, GoHighLevel's api, widgets and services domains, the FastPayDirect payment host, YouTube frames and Google Fonts. Add nosniff, SAMEORIGIN, a strict referrer policy and a permissions policy that turns off camera, microphone and geolocation.

   A developer who ships a CSP without testing the GHL booking widget will break lead capture on launch day.

8. Deploy to Cloudflare Pages

   • Push the repo to GitHub. In Cloudflare: Workers & Pages → Create → Pages → Connect to Git → pick the repo.
   • Framework preset Astro, build command npm run build, output directory dist. Save and deploy. Cloudflare gives a *.pages.dev preview URL immediately.
   • Review the site on the preview URL. Test every form, the booking widget, the chat widget and the tracking on the preview before touching DNS.
9. Cut over the domain

   • Move the domain's nameservers to Cloudflare if they are not already there. Wait for the zone to activate. mobilebillboardsf.com already sits behind Cloudflare, so this step is only a check that the account subdomain record and the mail records stay intact.
   • Pages project → Custom domains → add the apex domain and www. Cloudflare writes the DNS records and issues the certificate automatically.
   • The _redirects file must already be in the repo at this point. Old slugs 301 to new pages, old /blog/ to /resources/, old /about/ to /about-us/, and any slash-less versions of new URLs to their slashed form.
   • Google Search Console: verify the domain property, submit sitemap-index.xml. Update the Google Business Profile website link.
   • Keep the WordPress host alive for a couple of weeks in case something was missed, then cancel it.
10. Audit, fix, and set the ongoing workflow

    • Run a Search Atlas crawl, export the issues list, fix everything at severity 8 and above, re-crawl. Target 950+ per page.
    • Run PageSpeed on every page in the sitemap, mobile and desktop. Fix layout shift first. Our biggest win was a sitewide CLS of 0.275 caused by a translateY fade-in animation. Removing it took CLS to zero.
    • Set up a Google Cloud service account with PageSpeed, Search Console and Analytics Data APIs, grant it viewer access in GSC and GA4, and keep the JSON key outside the repo. Audit scripts save before and after JSON so every change is measurable.
    • Ongoing change workflow: edit, npm run build locally, review titles and descriptions, commit, push. Cloudflare deploys in about a minute. Re-crawl if SEO changed.

4. How it went for MFE

The commit history of the MFE repo shows the real pace. A candidate who has done this before will recognise the shape: a burst of scaffolding, then a dense SEO and tracking day, then a week of audit-driven fixes.

5. Details that prove experience

Anyone can follow an Astro tutorial. These are the things we learned in production. A strong candidate will volunteer several of them unprompted.

• Trailing slashes are a contract. Setting trailingSlash: 'always' is only half of it. Every internal link, canonical and sitemap entry has to match, or you get 308 chains that Search Console reports as redirect errors.
• Redirects come from Search Console, not from the sitemap. The URLs still earning impressions after a migration are usually junk slugs WordPress generated years ago. Those are the ones that need 301s.
• Keep the WordPress paths blocked in robots.txt on the new site. Google's index still holds them for months. Blocking stops crawl budget being wasted on 404s.
• CSP lives in _headers, redirects in _redirects, both in public/. Cloudflare Pages reads them from the build output. Putting headers in astro.config does nothing on a static build.
• Meta Pixel direct, GA4 through GTM. A tag manager pixel that fires on 80% of pageviews is worse than useless because you will trust the numbers.
• Fonts via link tags with preconnect and an async onload pattern. A CSS @import for Google Fonts is render-blocking and shows up immediately in PageSpeed.
• Scroll animations must not use transform translateY. Opacity only. Otherwise every section shifts on load and CLS fails sitewide.
• Explicit width and height on every image, WebP everywhere, lazy loading on everything below the fold.
• Dynamic canonical and og:url from Astro.url.pathname. Hardcoding the homepage URL into the layout means every page claims to be the homepage.
• No duplicate brand name in titles. "Mobile Food Experts | Mobile Food Experts" is a real mistake that a template produces and an auditor penalises. Pass a separate OG title prop.
• Build locally before every push. A failed Cloudflare build leaves the old version live, which is safe, but it should never be how you find out about a syntax error.
• Credentials never enter the repo. The service account JSON key sits outside the project and is referenced by absolute path.
• Scripts use .cjs when package.json declares "type": "module", or Node refuses require().
• Third-party embeds decide the CSP. GHL alone needs three domains allowed. Test every widget on the preview URL with the headers file in place.

6. Interview questions

Ask these in order. Each one has a specific answer we already know from doing the work, so a vague reply is easy to spot. Do not lead with the answer.

WordPress side

Astro

GitHub and Cloudflare

Tracking and integrations

Working style

7. Practical test

A paid trial on the real job beats any interview. Give the candidate the WordPress export of mobilebillboardsf.com, the logo and truck photos, the inventory in section 1, and this brief. Time box: three working days. Stage one is the first day and is enough to decide whether to continue.

Stage one, day one: foundation

• A private GitHub repo you can inspect, with a clean commit history and no node_modules or dist tracked
• A Cloudflare Pages preview URL deployed from that repo, on their own account
• Homepage, about, our team, FAQ, and the calendar page with the real GHL booking widget loading
• astro.config with static output, site URL, trailing slashes, sitemap
• BaseLayout with dynamic canonical, Open Graph, Twitter card, favicons, preconnected fonts via link tags
• _headers with a CSP that still lets the GHL widget load
• robots.txt with WordPress paths blocked, sitemap-index referenced

Stage two, days two and three: the rest

• All 13 pages and 4 posts rebuilt at their existing paths, posts kept at the root
• Blog listing page with CollectionPage schema, Article schema on each post, FAQPage schema on the FAQ page
• LocalBusiness and Organization JSON-LD with the Sioux Falls address, phone, and social profiles
• Gallery rebuilt with WebP images, explicit dimensions, lazy loading
• _redirects covering every old URL that changed, plus the slash-less versions of calendar, schedule and download-pricing
• GTM snippet in place with a placeholder container ID, Meta Pixel placeholder direct in the layout
• llms.txt listing every page and post
• A README with the deploy steps, the DNS cutover checklist including the account subdomain, and what they would do next

How to grade it

• Run PageSpeed on the preview URL. Mobile performance above 85 and CLS under 0.1 on the homepage and gallery is the bar.
• Open /calendar without the slash and confirm one redirect, not two, then confirm the booking widget actually renders with the headers file in place.
• View source on a blog post and confirm the canonical is that post, not the homepage, and that Article schema is present.
• Diff their redirect file against the URL table in section 1. Anything missing is a lost ranking.
• Check the commit history. Fifteen to thirty meaningful commits is healthy. One giant commit is a warning sign.
• Ask them what they would change with another day. The answer should include Search Console setup, real GTM and GA4 IDs, and a Search Atlas or Lighthouse audit.

8. Scoring sheet

Score each area 0 to 3. Under 14 total is a no. Weight the practical test heaviest.