Skip to content

fix: support GitHub Pages docs.rtf subpath routing - #2

Merged
zskbot merged 12 commits into
mainfrom
fix/github-pages-subpath-routing
Nov 12, 2026
Merged

zskbot merged 12 commits into
mainfrom
fix/github-pages-subpath-routing

Conversation

@zskbot

@zskbot zskbot commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Add shared browser base-path routing for GitHub Pages at https://ocodejs.co/docs.rtf/.
  • Keep Cloudflare Pages Preview rooted at / and avoid forcing the docs prefix on root-hosted /studio.html.
  • Apply base-path rewriting to dynamically generated course cards after filtering, including native link copy/open actions.
  • Publish the shared browser helper as a static asset.
  • Replace brittle source-string checks with behavioral Node tests covering host/path detection, navigation URLs, generated anchors, root deployment, and Cloudflare Preview.
  • Run behavioral tests as part of every npm run build.

Validation

Safety

  • No DNS or custom-domain configuration changes.
  • GitHub Pages Production remains unchanged until this PR is merged.
  • Cloudflare Pages automatic Production deployments from main remain disabled.
  • PR remains open for review; not merged.

@sourcery-ai

sourcery-ai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

API

Add a shared base-path helper that detects the GitHub Pages /docs.rtf subpath and provides path-building and link-rewriting functions for its callers.

  • scripts/base-path.mjs L1-22

Uses of the API

Use the shared helper in the frontend so navigation, rendered links, dynamically filtered course links, and AI Studio’s return links stay under /docs.rtf when appropriate.

  • index.html L69-75, L81, L100-101
  • studio.html L34-37

Configuration

Publish the browser helper and run its behavioral tests as part of the site build.

  • package.json L7-8
  • scripts/build-site.mjs L7, L31-32

Documentation

Document the GitHub Pages base path, the root-based Cloudflare Preview behavior, and the staging deployment details.

  • DEPLOYMENT.md L12-14, L23-24
  • README-IMPLEMENTATION.md L23

Tests

Cover host and path detection, client navigation, link rewriting, and root deployments to guard the subpath-routing behavior.

  • scripts/base-path.test.mjs L1-62

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@qodo-code-review

Copy link
Copy Markdown

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Deploying ocodejs-docs-rtf-staging with  Cloudflare Pages  Cloudflare Pages

Latest commit: d42b594
Status: ✅  Deploy successful!
Preview URL: https://f2cace8f.ocodejs-docs-rtf-staging.pages.dev
Branch Preview URL: https://fix-github-pages-subpath-rou.ocodejs-docs-rtf-staging.pages.dev

View logs

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ❌ Failed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ❌ Failed 2026-11-12T16:17:10.429616Z
We couldn’t complete this review. Comment @codex review to try again.
d42b594 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sourcery assessment

Approved.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 3 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="index.html" line_range="101" />
<code_context>
+app.innerHTML=out;wire();applyBaseLinks(document)}
</code_context>
<issue_to_address>
**Filtered course links leave Pages path**

When a visitor filters courses under `/docs.rtf` and opens or copies a generated course link using a browser-native link action, `filter()` replaces `#coursegrid` with `courseCard()` links whose root-relative `href` values are not passed through `applyBaseLinks()`. Native navigation therefore leaves `/docs.rtf` and does not reach the course page.

Apply the base path to newly generated course links, or generate them with base-prefixed `href` values.
</issue_to_address>

### Comment 2
<location path="studio.html" line_range="36" />
<code_context>
+if(BASE_PATH)document.querySelectorAll('a[href^="/"]').forEach(a=>{const href=a.getAttribute("href");if(href!==BASE_PATH&&!href.startsWith(BASE_PATH+"/"))a.setAttribute("href",BASE_PATH+href)});
</code_context>
<issue_to_address>
**Studio links force the subpath**

When a user opens the root-deployed `/studio.html` on `ocodejs.co`, outside `/docs.rtf`, `studio.html` sets `BASE_PATH` to `/docs.rtf` for every path on `ocodejs.co`, unlike `index.html`, which requires the current path to start with `/docs.rtf`; its rewritten links leave the root deployment and lead to the wrong route.

Use the same pathname-qualified base-path predicate in `studio.html` as in `index.html`.
</issue_to_address>

### Comment 3
<location path="scripts/build-site.mjs" line_range="25" />
<code_context>
   if (!/border-radius\s*:\s*0/i.test(source)) {
     throw new Error(`${file} must preserve square-corner controls`);
   }
+  if (file === "index.html" && (!source.includes("const BASE_PATH=") || !source.includes("function applyBaseLinks("))) {
+    throw new Error("index.html must support the GitHub Pages /docs.rtf subpath");
+  }
</code_context>
<issue_to_address>
**Build guard misses routing regressions**

When the routing code is reformatted without changing behavior, or a future edit breaks its behavior while leaving the checked strings in place, the source-string checks in `scripts/build-site.mjs` reject valid formatting changes but still pass when routing behavior is broken, so a routing regression can ship unnoticed.

Replace the exact source-string checks with tests that verify the base-path routing behavior.

Also at `scripts/build-site.mjs:28-29`.
</issue_to_address>

Sourcery assessment

Approval pending. 3 findings to address first.

Blocking findings: index.html:101, studio.html:36, scripts/build-site.mjs:25


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread index.html Resolved
Comment thread studio.html Resolved
Comment thread scripts/build-site.mjs Resolved
@zskbot
zskbot merged commit fb18560 into main Nov 12, 2026
4 checks passed
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.

1 participant