Skip to content

fix(docs): stop emitting an email-shaped string Cloudflare deletes (#93) - #95

Merged
eaitbrahim merged 1 commit into
mainfrom
fix/cf-email-obfuscation-93
Aug 27, 2026
Merged

fix(docs): stop emitting an email-shaped string Cloudflare deletes (#93)#95
eaitbrahim merged 1 commit into
mainfrom
fix/cf-email-obfuscation-93

Conversation

@eaitbrahim

Copy link
Copy Markdown
Contributor

Closes #93. A live regression from #85, found by checking production rather than dist.

What readers actually saw

Every engine document page rendered:

Fetched at build time from CodeGateSoftware/[email protected].

Cloudflare's Email Address Obfuscation matched keel@v0.11.2 as an address and rewrote it at the edge:

<a href="/cdn-cgi/l/email-protection" class="__cf_email__"
   data-cfemail="9af1fffff6daecaab4ababb4a8">[email&#160;protected]</a>

Decoding data-cfemail with its leading-byte XOR key returns keel@v0.11.2 — the origin response was always correct, only the served bytes were wrong. Which is exactly why npm run build and every CI check stayed green.

Why #85 caused it

The ${repo}@${ref} template predates the pin. Before it, ref was main, and keel@main has no dot after the @, so it does not look like an address. keel@v0.11.2 does.

The irony is exact: #85 existed to make the documented version visible, and the moment it became a version number the edge deleted it.

The fix, and why this one

Option Verdict
Turn off Email Address Obfuscation in the Cloudflare dashboard Zone-level, not reachable from this repo, global blast radius, and it silently regresses the day someone re-enables it
Stop emitting an email-shaped string Same information, matches no address pattern, cannot be undone by a setting

All three locales get a connector in their own language — at / عند / à — rather than a symbol. A comment on the template records why, so nobody tidies it back to @.

Same class as #82

An edge rewrite silently changing what the site says, invisible from inside the repo because dist was right. That is now twice. ai-crawler-check.yml already tests production for exactly this kind of thing — a sibling assertion for the version string is the obvious follow-up, noted on #93.

Verification

  • npm run check0 errors, 0 warnings
  • npm run build56 pages, complete
  • Zero CodeGateSoftware/keel@ occurrences in any built page
  • Renders in all three locales:
    • en — from CodeGateSoftware/keel at v0.11.2
    • ar — من CodeGateSoftware/keel عند v0.11.2
    • fr — depuis CodeGateSoftware/keel à v0.11.2

Production must be re-checked after deploy — the origin was never the problem, so a green build proves nothing here.

Reviewer attention

  1. Is at the right English connector, or would @ v0.11.2 with a space read better? A space defeats the matcher too, but it is easier to "fix" back into a defect later.
  2. The ar عند and fr à connectors are my choice — worth a native eye.

🤖 Generated with Claude Code

https://claude.ai/code/session_015cBJ2syTN4VoE73F9sBNGW

Closes #93. A live regression from #85, found by checking production rather
than `dist`.

### What readers actually saw

Every engine document page rendered:

> Fetched at build time from CodeGateSoftware/**[email protected]**.

Cloudflare's Email Address Obfuscation matched `keel@v0.11.2` as an address and
replaced it at the edge:

    <a href="/cdn-cgi/l/email-protection" class="__cf_email__"
       data-cfemail="9af1fffff6daecaab4ababb4a8">[email&#160;protected]</a>

Decoding `data-cfemail` with its leading-byte XOR key returns `keel@v0.11.2`, so
the origin response was always correct — only the served bytes were wrong.

### Why #85 caused it

The `${repo}@${ref}` template predates the pin. Before it, `ref` was `main`, and
`keel@main` has no dot after the `@`, so it does not look like an address.
`keel@v0.11.2` does.

The irony is exact: #85 existed to make the documented version visible, and the
moment it became a version number the edge deleted it.

### The fix, and why this one

Two remedies existed. Turning Email Address Obfuscation off is a zone-level
dashboard setting — not reachable from this repo, global in blast radius, and it
would silently regress the day someone re-enables it.

Emitting `repo at ref` instead carries the same information, matches no address
pattern, and cannot be undone by a setting. All three locales get a connector in
their own language — `at` / `عند` / `à` — rather than a symbol.

A comment on the template says why, so nobody tidies it back to `@`.

### Same class as #82

An edge rewrite silently changing what the site says, invisible from inside the
repo because `dist` was right. That is the second time; #93 suggests a
production assertion, and `ai-crawler-check.yml` is the pattern to copy.

### Verification

- `npm run check` — 0 errors, 0 warnings
- `npm run build` — 56 pages, complete
- Zero `CodeGateSoftware/keel@` occurrences in any built page
- Renders in all three locales:
  - en — `from CodeGateSoftware/keel at v0.11.2`
  - ar — `من CodeGateSoftware/keel عند v0.11.2`
  - fr — `depuis CodeGateSoftware/keel à v0.11.2`

Production must be re-checked after deploy: the origin was never the problem.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015cBJ2syTN4VoE73F9sBNGW
@sonarqubecloud

Copy link
Copy Markdown

@eaitbrahim
eaitbrahim merged commit b35c2d6 into main Aug 27, 2026
2 checks passed
@eaitbrahim
eaitbrahim deleted the fix/cf-email-obfuscation-93 branch August 27, 2026 00:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cloudflare's email obfuscation is eating the docs version provenance: "from CodeGateSoftware/[email protected]"

1 participant