Replace a hosted builder

Website.md is useful when the site is simple enough to become source files, local previews, checks, and a deploy pipeline. URL preservation is the main reason to use it for a migration: you keep search equity, bookmarks, and inbound links instead of silently breaking paths.

1. Export or copy existing content

Inventory every public URL from the current builder: home, about, services, blog posts, legal pages, and campaign landers. Export text, images, and metadata where the platform allows it. Save a spreadsheet of old URL → page title → primary content file.

2. Create a Website.md starter

npm create website-md@latest my-site
cd my-site
npm run dev

Open the folder in your AI agent. You only need WEBSITE.md to start; add optional companion files later if the site grows.

3. Map old URLs in WEBSITE.md

In ## Site Structure and ## Canonical URLs, list every URL that must keep working. Example:

## Canonical URLs

Preserve these public URLs exactly:

- /
- /about
- /services
- /blog/welcome-post

Ask the agent to rebuild each page as static HTML or Markdown under src/ while matching the old slug.

4. Preserve canonical URLs

Each page needs a matching <link rel="canonical"> and stable path. Do not rename slugs for style points during migration. If a URL must change, treat it as a redirect task—not a silent rename.

5. Add redirects where needed

When a path cannot be recreated exactly, add host-specific redirects:

Document every redirect in WEBSITE.md under Canonical URLs or Redirect Policy.

6. Run the checker

npm run build
npm run check
npx website-md check

Fix missing sections, broken file references, and script gaps before deploy.

7. Deploy

Deploy dist/ to Vercel, Netlify, Cloudflare Pages, or GitHub Pages. Verify every preserved URL returns 200. Spot-check metadata and mobile layout on the top traffic pages.

8. Point the domain

Lower DNS TTL a day before cutover. Attach the custom domain in the host dashboard. Keep the old builder live until redirects and the homepage are verified on production.

Ask before changing

Do not migrate forms, analytics, domains, checkout, or payment flows without explicit approval. Those systems often carry compliance and billing risk.

Create a new site guide · Real example