[uniqueg]

Summary

Build and host the docs on Read the Docs (RTD), with pull request previews and per-branch builds, replacing the Vercel previews and the Rahti deployment.

• .readthedocs.yaml: builds the docs app with npx turbo run build --filter=ecc-docs... and publishes apps/documentation/out.
• RTD serves each version under a subpath (/en/latest/, /en/<branch>/, /en/<pr>/). When READTHEDOCS_CANONICAL_URL is set, next.config.js derives basePath from it and writes trailing-slash directories. Hard-coded root paths become base-path aware: next/image sources and the favicon go through a small withBasePath() helper, internal links use next/link, and the hero button uses the router.
• NEXT_PUBLIC_BASE_PATH is always set from the RTD URL (empty without it), so a stray value in the environment can't prefix assets.
• turbo.json: declares the two variables for the build task (required by the turbo/no-undeclared-env-vars lint rule; also puts them into turbo's cache key).
• Without the variable (Docker image, Vercel), the build output is unchanged except for:
  • the attribute order on the converted links, which now navigate client-side, as Nextra's own links do;
  • the head: declaring the favicon replaces Nextra's default head, so the custom head keeps its generic tags (Content-Language, msapplication-TileColor) and drops Nextra's own branding (the "Nextra: the next docs builder" description, Open Graph and Twitter tags).

Commits: the subpath support, the favicon fix found while testing on RTD, and fixes from the pre-push review.

Closes #475

Notes

• Node.js 24 on RTD, matching the docs image in build: move CI and Docker to Node.js 22 and 24 #470 (not merged yet; until then the Dockerfile on dev still uses Node.js 20). If build: move CI and Docker to Node.js 22 and 24 #470 settles on another version, change build.tools.nodejs accordingly.
• Docs URL: the final RTD URL is only known after the import into RTD, so the links to Rahti (README) and Vercel (package READMEs, scripts/templates/custom-elements-manifest.config.js) stay as they are. Follow-up once the URL is known.
• No workflow files are touched (CI is being restructured in chore: align tooling and hygiene with the org #464).
• Branches: dev (with chore: remove leftovers, pin actions #469, build: move CI and Docker to Node.js 22 and 24 #470 and test: drop test scripts of packages without tests #478) is merged in (2026-10-27, head 20e93df); this PR is not stacked on ci: single CI gate and contribution docs #474. CI on that head: PR Evaluation (linting, tests on Node.js 22 and 24) and the RTD build pass.
• RTD check: the RTD build check and preview comment appear on pull requests only after the human steps in docs: host the docs on Read the Docs #475 (import under the org, enable pull request builds).

Verification

Tested on an RTD project for the fork uniqueg/cloud-components (same two commits on top of v2.0.0-alpha.48, with Node.js 20): the main build, pull request previews, per-branch builds through an automation rule (only for branches created after the rule) and the favicon fix work.

Locally, with Node.js 24.22.1 / npm 11.19.1:

• npm ci --no-audit --no-fund: passes, lockfile unchanged.
• npm run lint: passes.
• npm run build (no RTD variable): passes; output at the root path, favicon at /favicon.ico. With NEXT_PUBLIC_BASE_PATH=/stray and no RTD variable: no /stray anywhere in the output.
• RTD sequence (npx turbo run build --filter=ecc-docs...) with READTHEDOCS_CANONICAL_URL set to https://cloud-components.readthedocs.io/en/latest/ and https://cloud-components--123.org.readthedocs.build/en/123/: passes.
• Static scan of the 46 exported HTML files per variant: no root-absolute src/href outside the base path.
• Nextra's search index loads under the base path (/en/latest/_next/static/chunks/nextra-data-en-US.json, 200).
• Playwright (headless Chromium), each export served under /en/latest/ and /en/123/: home page, styles and web font, logo and footer images, hero button, "View More Components" link, intro doc links, sidebar navigation, checkbox/collapsible/input demos, TRS tools component, path without trailing slash. Remaining page errors are pre-existing (getSelectId is not a function on the home page, the same on main) or come from the offline sandbox (live demo APIs).

CI: Linting checks, Semantic PR title and Detect unresolved merge conflicts pass. Two failures are unrelated and the same on the other open PRs:

• Test checks (20.x) fails at "Install playwright" (Playwright does not support chromium on ubuntu26.04-x64: ubuntu-latest moved on); 18.x is cancelled with it. The runner pin in chore: remove leftovers, pin actions #469 addresses this.
• Vercel fails on every current PR (chore: remove leftovers, pin actions #469, build: move CI and Docker to Node.js 22 and 24 #470, ci: npm trusted publishing and GitHub releases #473); Vercel is to be retired in favour of RTD (docs: host the docs on Read the Docs #475).

Declined review findings

• Node.js 24 on RTD vs. Node.js 20 in the Dockerfile and CI on main: deliberate, to match build: move CI and Docker to Node.js 22 and 24 #470 (docs image on node:24-alpine); the comment in .readthedocs.yaml says so. Merge build: move CI and Docker to Node.js 22 and 24 #470 first, or switch to "22"/"20" here if build: move CI and Docker to Node.js 22 and 24 #470 changes.
• NEXT_PUBLIC_BASE_PATH in turbo.json is not a real input: the turbo/no-undeclared-env-vars lint rule fails without it; the only effect is on turbo's cache key.
• Hero button: wrap in next/link instead of router.push: the button is a web component; nesting it in an anchor nests interactive elements. router.push applies the base path and keeps the current behaviour.
• Squash the commits, use feat/build instead of docs: the repository squash-merges with the PR title; the change only affects the docs site, so docs: fits.
• Real RTD build before merge: done on the fork (see Verification); the upstream RTD check needs the import in docs: host the docs on Read the Docs #475 first.

Open questions

None.

🤖 Generated with Claude Code

Summary by Sourcery

Host the documentation site on Read the Docs with reliable branch and pull-request previews and subpath-aware navigation and assets.

New Features:

• Configure Read the Docs to build and publish the documentation site, including versioned subpath deployments for branches and pull requests.

Bug Fixes:

• Ensure documentation assets, favicon, and navigation work correctly when the site is served from a Read the Docs subpath.

Enhancements:

• Make internal documentation navigation base-path aware while preserving unchanged root-path builds outside Read the Docs.
• Customize the documentation head metadata and branding for the hosted site.

Build:

• Declare Read the Docs and base-path environment variables as documentation build inputs for Turbo.

Deployment:

• Replace the documentation hosting configuration with a Read the Docs build and deployment configuration.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
elixir-cloud-components	Error		Oct 26, 2026 8:33pm UTC

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9d5fe5c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[sourcery-ai]

Reviewer's Guide

The PR moves documentation hosting from Vercel/Rahti to Read the Docs and implements build-time subpath support for versioned and pull-request previews. Next.js configuration, asset URLs, internal navigation, favicon handling, and Turbo environment declarations are updated while retaining unchanged root-path behavior outside RTD.

Sequence diagram for base-path-aware documentation build

sequenceDiagram
    participant RTD as Read the Docs
    participant Next as Next.js build
    participant Turbo as Turbo
    participant Site as Static documentation output

    RTD->>Next: Set READTHEDOCS_CANONICAL_URL
    Next->>Next: Derive basePath and trailingSlash
    Next->>Next: Set NEXT_PUBLIC_BASE_PATH
    RTD->>Turbo: npx turbo run build --filter=ecc-docs...
    Turbo->>Next: Build documentation app
    Next->>Site: Write base-path-aware assets and links
    RTD->>Site: Publish apps/documentation/out

Loading

Flow diagram for base-path-aware documentation navigation

flowchart TD
    Page["Documentation page"] --> Asset["withBasePath() for images and favicon"]
    Page --> Link["next/link for internal links"]
    Page --> Hero["router.push('/docs/introduction')"]
    Asset --> Base["RTD base path or empty root path"]
    Link --> Base
    Hero --> Base

Loading

File-Level Changes

Change	Details	Files
Configure Read the Docs to build and publish the static documentation site, with the required Node.js and Turbo build settings.	Add RTD v2 configuration using the documentation app’s Turbo build and publish its exported output. Set the Node.js build version and document that pull-request and branch previews are enabled through RTD project settings. Declare RTD/base-path environment variables in the Turbo build task for linting and cache-key correctness.	.readthedocs.yaml turbo.json
Add environment-driven support for serving the documentation under Read the Docs version and pull-request subpaths while preserving root-path deployments.	Derive Next.js basePath and trailing-slash export behavior from READTHEDOCS_CANONICAL_URL. Override NEXT_PUBLIC_BASE_PATH from the derived value so unrelated environment values cannot prefix assets. Add a shared helper for prefixing public assets with the configured base path.	apps/documentation/next.config.js apps/documentation/utils/basePath.ts
Make documentation assets and navigation work correctly when exported beneath a subpath.	Prefix logos, footer images, and the favicon with the configured base path. Replace root-relative internal anchors with Next.js links for client-side, base-path-aware navigation. Route the hero web-component button through Next.js so navigation applies the configured base path without nesting interactive elements.	apps/documentation/components/common/Footer.tsx apps/documentation/components/home/Hero.tsx apps/documentation/components/home/ServicesShowcase.tsx apps/documentation/pages/docs/introduction.mdx apps/documentation/theme.config.tsx
Customize the generated document head for the hosted site and explicitly provide a base-path-aware favicon.	Replace Nextra’s default head with the retained generic metadata and a favicon link. Drop Nextra-specific branding and social metadata from the custom head.	apps/documentation/theme.config.tsx

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#475	Configure the documentation app to build and publish on Read the Docs, supporting pull-request previews and per-branch versions.	✅
#475	Make the documentation work under Read the Docs version subpaths—including assets, favicon, internal navigation, and the hero action—while preserving root-path builds when the RTD URL is unset.	✅

Possibly linked issues

• docs: host the docs on Read the Docs #475: The PR implements the issue’s RTD hosting, versioned builds, and subpath support; it explicitly closes docs: host the docs on Read the Docs #475.

---

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

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Approved.

---

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

• X
• Mastodon
• LinkedIn
• Facebook