Skip to content

For the complete documentation index, see llms.txt.

Preserve URLs and redirects

A migration usually changes your page URLs. The new platform lays out paths differently, and section names shift as you restructure. Every inbound link, bookmark, and search result that points at an old URL then returns a 404 error. Redirects send readers and search engines from each old URL to its new page, so the move stays invisible to your readers.

This guide covers building an old-to-new URL map, adding permanent redirects, and verifying them around cut-over. The same steps apply when you restructure an existing docs set on the same platform.

Your documentation platform and host serve redirects. Promptless proposes content changes through pull requests and doesn’t manage your hosting-level redirects.

  • A list of your published URLs. If your source platform can export one, start from that export so you don’t miss a page. Crawling your live site also lists every URL that needs a destination.
  • Access to your target platform’s site configuration or your host’s redirect rules.

Record where every old URL lands in the new structure. Capture the mapping while you move content, when the correspondence is freshest. A two-column mapping from old path to new path is enough:

Old pathNew path
/kb/getting-started/docs/get-started/quickstart
/reference/api-overview/docs/reference/api

Every page whose URL changes needs an entry. Pages that keep their URL don’t.

Add a permanent (HTTP 301) redirect from each old path to its new one. A permanent redirect tells search engines to transfer ranking to the new URL. Where you add the rules depends on your target platform and host:

  1. Check your platform’s and host’s documentation for how they read redirects. Most read them from a redirects map in your site config, or from a hosting-level redirects or rewrites file.

  2. For each row of your URL map, add a permanent (301) redirect rule from the old path to the new path.

  3. Optional. When a whole section moves under a new prefix, replace that section’s per-page rules with one wildcard or pattern redirect. This step requires a platform that supports pattern-based rules.

Confirm the redirects resolve before you point your domain at the new site, and again once it’s live:

  • Spot-check your most-visited old paths from your analytics, and confirm each one lands on the right new page.
  • Crawl the new site with a link checker to find any internal link or redirect that points at a dead path.
  • After cut-over, watch your host or analytics logs for 404 errors, and add any redirect you missed.

Promptless also handles redirects for the URLs its own suggestions change. When a suggestion retires, moves, or renames a page, or changes its slug, the same suggestion:

  • Adds a permanent redirect from each removed URL to the page that now covers the topic. The redirect goes next to the redirects your collection already keeps, such as a framework setting or your host’s configuration file. When no page covers the topic, the redirect points at the nearest overview page, and the suggestion calls out that choice for review. The suggestion also calls out the first redirect in a collection that has none yet.
  • Updates links elsewhere in the collection to point straight at the new page. When a sentence only existed to send readers to a retired feature, the suggestion rewords it.
  • Keeps the page and adds a deprecation notice when the feature is deprecated but still works. The notice links to the replacement and gives a removal date only when the source change establishes one.

Promptless retires a page only when no supported release has the behavior it describes. A page that still describes current behavior stays, however old it is or however few readers it has. Links to a removed URL from outside the collection, such as your product’s interface or another repository, keep working through the redirect. Whoever owns those links decides whether to update them.