Try your first idea

In this tutorial you try two new headlines on a home page, beside the current one: you declare the page, write the slot in your template, stamp it, look at each headline on your machine, check what will go live, deploy, and look at a variant in production. It follows RoutingCat’s example static site, whose setup is done: plain HTML pages, in the same markup a Hugo, Jekyll or Blade template carries. You ask your agent “Try two new headlines on the home page”, and it takes these steps with you.

1. Choose the shape

The idea needs one place on one page: a page home with one slot, hero, whose variants are headlines.

The current headline becomes the default, under its own key, current. The control keeps seeing it, so the measured gain compares routing with what your site shows today.
Each new idea gets a new key, so that it is compared with the default at the same time, on the same traffic.

Your agent writes the headlines from what your site already says. A claim, such as a number, a testimonial or a price, must be true, so it comes from your site or from you. A headline and a button would be two slots; a redesign would be one slot holding the page’s whole content. See Pages, variants and versions.

2. Declare the page

routingcat.config.json names each page you route, with its routes and a representative URL, which doctor reads. The example site’s declares its home and pricing pages, its main conversion, waitlist, and what each new variant tries:

{
  "$schema": "https://cdn.routingcat.com/schemas/1.0.3/config-1.json",
  "site": "routingcat-static-example",
  "public_key": "pk_routingcat-static-example_Tc5Wm9Rb",
  "integration": "cloudflare",
  "sources": ["public/**/*.html"],
  "head": { "partial": "routingcat-head.html" },
  "objective": "waitlist",
  "pages": {
    "home": { "routes": ["/"], "url": "/" },
    "pricing": { "routes": ["/pricing"], "url": "/pricing" }
  },
  "variants": {
    "home/hero:learns": { "description": "Lead with learning" },
    "home/hero:shows": { "description": "Lead with each visitor's own page" },
    "home/subhead:short": { "description": "Half the words" },
    "pricing/lead:start": { "description": "Lead with the free start" },
    "pricing/trial:days30": { "description": "A longer trial" }
  }
}

An address names each variant, as home/hero:learns, in commands and on the dashboard. Under variants, by its address, each new variant says what it tries, as its description: it never shows on your pages and makes no version, and npx routingcat show home/hero:learns prints it above the variant’s version, so that you and your agent know later what each idea tried. A name and tags can go beside it.

3. Write the slot

In the page’s template, the slot is a container holding every variant, the current headline first. Here it is as the example’s home page carries it:

      <div data-rc-page="home" data-rc-slot="hero" style="display:contents">
        <div data-rc-variant="current" data-rc-hash="214ccf813b46030bb649a04128e2863d5ace330ed9b0088cc64e18a2286cc6eb" style="display:contents">
          <h1>Route every visitor to what converts</h1>
        </div>
        <div data-rc-variant="learns" data-rc-hash="f0197a0807eb3b098f2e1fb122e5e62a89ef6da4e7fc72f8dae6b0e4b5599202" hidden data-nosnippet>
          <h1>Your pages learn what converts each visitor</h1>
        </div>
        <div data-rc-variant="shows" data-rc-hash="772f7208a1f629e488de631d7b939443bb84344293a1035ea876380fe41eaf31" hidden data-nosnippet>
          <h1>Show each visitor the page that converts them</h1>
        </div>
      </div>

You write the container with data-rc-page and data-rc-slot, and each variant with data-rc-variant: the default without hidden, every other variant with it.
push adds the rest in the next step: each variant’s data-rc-hash, style="display:contents" on the container and the default, and data-nosnippet on hidden variants, which keeps their text out of the snippets search engines show.

Without RoutingCat, the page shows its defaults and nothing else. With it, the head snippet shows each visitor’s own variant before the page paints. Build a page gives the rules hidden markup follows.

4. Stamp it

npx routingcat push

On a Hugo site whose home page has a slot of four variants, freshly written:

$ routingcat push
lumen · 1 template · 1 slot, 4 variants
stamps    9 edits
  layouts/index.html:2   home/hero           style="display:contents"
  layouts/index.html:3   home/hero:current   data-rc-hash 58c2042d15ca…
  layouts/index.html:3   home/hero:current   style="display:contents"
  layouts/index.html:6   home/hero:oneclick  data-rc-hash c4a2d99ee3bd…
  layouts/index.html:6   home/hero:oneclick  data-nosnippet
  layouts/index.html:9   home/hero:studio    data-rc-hash 975b5d620955…
  layouts/index.html:9   home/hero:studio    data-nosnippet
  layouts/index.html:12  home/hero:best      data-rc-hash c37fb91bad3a…
  layouts/index.html:12  home/hero:best      data-nosnippet
partial   layouts/partials/routingcat-head.html: written
· Your build registers these templates on every deploy, through routingcat build. Commit what routingcat push changed; routingcat plan shows what a deploy would make live.  (D72)

push registers nothing: it writes the version of each variant into your templates, and keeps the head partial current. Commit what it changed. Your build then refuses stale stamps, and a head partial other than the one push writes, so a deploy never reports other versions, or runs another snippet or tracker, than it registers.

5. Look at each headline on your machine

Run your site’s build, if it has one, as hugo, then npx routingcat build, then your host’s local server: wrangler dev on Cloudflare Workers, wrangler pages dev on Pages, vercel dev on Vercel. On Workers or Pages, a package.json script that runs Wrangler’s server runs routingcat build before it, as init set it. This build registers nothing, and its pages run in development mode: they show the defaults and record nothing. Open the home page with ?rc=hero:learns at the end of its URL: it shows that headline until you open it with ?rc=off. The choice lasts for the browser session. It works for any variant your templates held at your last routingcat build, so run push and routingcat build again after each edit. See a variant in development gives the details.

6. Check what will go live

npx routingcat plan

On the same Hugo site:

$ routingcat plan
lumen · this code against production (dp_01m3yfqdsgfkr9jahvnyvk6gaa, commit 4be1c07) · contract 1.0

home  new page · route / · objective signup, 24 h (from routingcat.config.json)
  hero  new slot · default current
    + current   "Edit photos like a pro"                  the default, which the control always sees
    + oneclick  "Pro-level photo edits in one click"      scorecard against current
    + studio    "Your photos, studio-ready"               scorecard against current
    + best      "Make every photo your best one"          scorecard against current

In production this goes LIVE, with routing within about 2 minutes:
  the control keeps seeing the defaults · the random slice of visits is split evenly
  the rest are routed toward signup, as the model learns which variant works for whom
A production deploy applies only what its code changed since the previous production deploy.
A preview deployment registers these versions and changes nothing live.

limits    4 of 100 variants · 1 of 20 slots · 4 of 1,000 combinations
          the site: 3 live variants, the defaults not counted, of the 10 the Hobby account's sites share
valid     routingcat build will accept this                                       (exit 0)

plan reads your templates and your config as the build will, compares them with what production serves, and registers nothing:

each new headline is marked +, with a scorecard against current from the moment it goes live;
on Hobby, its limits line counts the site’s live variants, the defaults not counted, toward the 10 your account’s sites share: past them, a new variant is held rather than served, and plan marks it;
exit code 0 means the build will accept the page; 1 means it would reject it, and the line says what to fix, such as a page the markup names that routingcat.config.json doesn’t declare.

Your agent tells you what will go live, in plain words, before you deploy.

7. Deploy

Commit and deploy to production. RoutingCat’s line in the build log confirms it, here for a hero of four variants:

$ routingcat build
routingcat  LIVE home: 4 variants in hero, routing within about 2 minutes (ch_01m40j70srer495wr3vhnyvjca, pb_01m40j70srfb59gbvnmr3nv2t6)

This deploy changes what visitors see. Within about 2 minutes, 90% of your visitors are routed between the headlines; the control keeps seeing current. A preview deployment would only register the headlines.

On Hobby, routing waits for a card on file. Until the site’s owner adds one, the line reads routingcat NOT LIVE routing waits for a card on file: add one at …, nothing charged, and the page keeps serving current. Routing starts within about 2 minutes of the card, with no new deploy: see Add a card to start routing.

npx routingcat doctor --wait now adds three checks for the page: home live, first decision and first render beacon. The last arrives once a browser shows the page.

8. See a variant in production

npx routingcat preview home/hero:learns

It prints a signed link, valid for one hour, that opens your home page with that headline and a small preview badge. The visit stays out of results, and your own variants stay as they were. See Change, preview and deploy.

9. Watch the first days

Routing learns once a day on Hobby, and on Pro as conversions mature, at most hourly, from visits whose window has closed. With the 24-hour window, a visit starts to shape routing a day or two later on Hobby, about a day later on Pro.
New headlines start cautiously, at signal New, with a limited share of visits until evidence builds. A small random slice of visits is always split evenly.
The measured gain starts wide. It shows no range while visits are few, then a range; while that range spans zero, the direction isn’t known yet.
Wait for the evidence. Checking every day and acting on the first good day overstates gains.

Ask your agent “How is it going?”: it runs npx routingcat status and says each number with how sure it is. See Read and explain results. The page’s screen on your dashboard shows the same figures: see Read the dashboard. Once one headline is clearly ahead, promoting it makes it the default; see Change what’s live.