Skip to main content

​
Methodology migration: marketing /guides to docs /methodology

Status: plan only. Nothing in this document has been applied. The six docs pages and the docs.json navigation group are written. No marketing file has been touched and no redirect has been configured.

​
Why

The docs subdomain ranks around position 4 to 5 for the queries these guides target. The equivalent marketing guides sit near position 85. The working hypothesis is that Google reads docs.abtestly.com as an informational surface and abtestly.com/guides/ as a commercial one, so the same subject matter is being scored very differently depending on where it lives. Moving the material and 301ing the old URLs tests that hypothesis directly.

​
1. Redirect map (301, permanent)

Two of the six new pages have no old counterpart and need no redirect:
  • https://docs.abtestly.com/methodology/sample-ratio-mismatch (new; a methodology sibling to the existing /results/srm, which stays where it is and keeps its own inbound links and its in-product deep link from the results banner)
  • https://docs.abtestly.com/methodology/confidence-intervals (new)

​
Landing page URL: resolved

The landing page is methodology/overview.mdx, served at https://docs.abtestly.com/methodology/overview. It was originally written as methodology/index.mdx. That was changed deliberately, for two reasons. Every other section in this repo already uses overview.mdx (targeting/overview, goals/overview, signals/overview, exclusion-groups/overview), so index would have been the only exception. More importantly, a self-referential 308 loop from an /index redirect has taken this docs site down once before, and overview removes the ambiguity rather than leaving it to be discovered in production. Do not add { "source": "/methodology", "destination": "/methodology/overview" } to the redirects array in docs.json. It is not needed, Mintlify renders the group from the nav, and that shape of self-referential redirect is exactly what caused the earlier outage. After the docs deploy, confirm the target answers before pointing live traffic at it:
If that returns 200, the redirect table below is correct as written.

​
2. Marketing-side changes required

None of these have been made. File paths are relative to the marketing package root. Line numbers are as of this audit.

​
2.1 Sitemap: public/sitemap.xml

Remove four <url> blocks, lines 141 to 164 inclusive (24 lines). The file currently holds 33 <url> entries and would hold 29. Removing a URL from the sitemap does not retire it from the index. The 301 is what does that. Keep the entries in place until the redirects are live, then remove them, so Google is not asked to recrawl a page that still resolves 200 with no forwarding.

​
2.2 Build inputs: vite.config.js

Remove four rollupOptions.input entries, lines 39 to 42:
A page absent from that object is never copied to dist/, so removing these four lines is sufficient to stop shipping the guides. Deleting the four source files under guides/ is optional and carries a test consequence, see 2.5.

​
2.3 AI crawler manifest: public/llms.txt

Lines 29 to 35 are a ## Guides section listing all four URLs:
This file is copied to the dist root verbatim and is what AI engines read to describe the product. Repoint the four URLs at the docs equivalents rather than deleting the section, and consider adding the two new pages (/methodology/sample-ratio-mismatch and /methodology/confidence-intervals) while you are in there. Two classes. The first is substantive body copy and needs repointing at the new docs URLs. The second is a repeated footer link. Body copy, repoint individually: Footer “Guides” link, one per page, all <a href="/guides/">Guides</a>: There is no shared footer partial. Every page carries its own copy, so this is 31 separate edits. The footer already links “Docs”, so one valid option is to drop the “Guides” list item entirely rather than repoint 31 links at docs.abtestly.com/methodology. That is a design decision, not a technical one.

​
2.5 Test consequence if you delete the guides/ directory

test/competitive-claims.test.mjs line 101 builds its scan list with an unguarded readdirSync(join(root, 'guides')). Deleting the directory makes npm test throw at module load rather than fail a claim, so if you remove the source files you must also update that readdir (the sibling scripts/inject-chat-widget.mjs already wraps its equivalent call in a try/catch and needs no change). The safer sequence is to remove the four vite.config.js inputs first, leaving the source files on disk. The pages stop shipping, the claims guard keeps scanning them, and nothing breaks. Delete the directory later as a separate change with the test fix attached.

​
3. How to serve the redirects

The marketing site has no _redirects file, and none anywhere in the repository. That is deliberate and worth preserving. Configure five source-to-target rules in the Cloudflare dashboard under Rules, Redirect Rules, Bulk Redirects, on the abtestly.com zone. Set status 301, preserve query string off, subpath matching off. Advantages:
  • It runs at the zone edge, before the Pages project is consulted, so it cannot interact with how Pages resolves extensionless URLs.
  • It survives a Pages redeploy, and it survives the marketing build losing the guides/ inputs. Order of operations stops mattering.
  • It is editable without a deploy, so a wrong target is a one-minute fix rather than a build and a propagation wait.
  • Cross-hostname redirects to docs.abtestly.com are exactly what the feature is for.
Disadvantages:
  • The rule lives in the Cloudflare dashboard and not in version control, so it is invisible to anyone reading the repository. Record the five rules in this file when you create them, and keep this file updated.
  • Bulk Redirects consume a redirect-list quota on the account.

​
Option B: a _redirects file in the marketing project

Cloudflare Pages reads _redirects from the build output root. Adding one would put the rules in version control alongside the pages they replace, which is the honest advantage. The risk is specific and this project has already been bitten by the neighbouring version of it. Pages serves this site’s extensionless URLs (/pricing for pricing.html) through its own clean-URL handling, and _redirects is evaluated in the same layer. A rule set that introduces a /guides/ source alongside that resolution has a real chance of either shadowing the clean-URL behaviour for the whole directory or creating a loop between /guides and /guides/. Introducing the file at all changes the request path for every URL on the site, not just the five being redirected, which is a wide blast radius for a small change. If Option B is chosen anyway, deploy it to a Pages preview branch first and verify with curl -sI that a representative sample of existing clean URLs still return 200 and that all five redirect sources return 301 with the right Location. Do not verify this from a browser: Cloudflare’s HTTP surface in front of this project is not a reliable read for cache and redirect behaviour, and a preview deployment tells you more than the production URL will.

​
Recommendation

Take Option A. The rules are cross-hostname, they need to outlive the marketing build losing its guide inputs, and the clean-URL interaction in Option B is a risk taken for a bookkeeping benefit.

​
4. Suggested order of operations

  1. Ship the docs pages and the docs.json navigation group. Verify the /methodology URL shape with the curl in section 1.
  2. Confirm the six pages appear in the Mintlify-generated sitemap at https://docs.abtestly.com/sitemap.xml, then submit that sitemap in Search Console. Mintlify generates it; there is no sitemap file in the docs repository to edit and none should be added.
  3. Configure the five Bulk Redirect rules. Verify each with curl -sI.
  4. Repoint the marketing body-copy links (section 2.4, first table) and public/llms.txt (section 2.3). These now point at live docs pages through a live redirect either way, so the order between 3 and 4 is not critical.
  5. Remove the four vite.config.js inputs and the four sitemap blocks. Deploy the marketing site.
  6. Leave the guides/ source files on disk. Handle the directory deletion and the competitive-claims.test.mjs readdir together, as a separate change.
  7. Watch Search Console for the four old URLs moving to “Page with redirect” and the five new docs URLs entering the index. Expect weeks, not days.

​
5. What this document does not cover

  • The docs.json redirects array was not touched. No docs-internal redirect is required by this migration.
  • /results/srm keeps its URL and its inbound link from the in-product SRM banner. The new /methodology/sample-ratio-mismatch page is a method reference beside it, not a replacement.
  • The marketing structured data on the guide pages (TechArticle, FAQPage, BreadcrumbList, and the CollectionPage on guides/index.html) goes away with the pages. Mintlify emits its own page metadata and the docs pages do not carry hand-written JSON-LD. Whether to reconstruct FAQ structured data on the docs side is an open question and out of scope here.
Last modified on September 6, 2026