jason810496 opened a new pull request, #72105: URL: https://github.com/apache/airflow/pull/72105
- related: #72097 - broken page: <https://airflow.staged.apache.org/docs/ts-sdk/stable/> ## Why The ts-sdk API reference publishes but renders unstyled: the HTML asks for `/_assets/styles...css`, which resolves against the domain root instead of `/docs/ts-sdk/...`. The theme also loads fonts from `fonts.googleapis.com`, which ASF privacy guidance allows only when ASF-hosted. ## How `clean-jsdoc-theme` defaults `basePath` to `/` and `typedoc.json` never set it. `basePath` is the **versioned** path, not `/docs/ts-sdk/stable`: `publish_docs_to_s3.py:178-195` syncs one build to both, so only one can own the assets. Pinning to the version keeps archived releases self-contained, since a later release replaces `stable/` via `sync --delete` without touching assets they still cite. Fonts cannot be fixed by config. The theme validates the families against the live Google Fonts API and restores its own defaults on a 400, so an override works offline and regresses in CI, where the build has network. Stripping the tags is the only reliable control point; the theme's CSS already declares the Georgia / system-ui fallbacks. ## What - `typedoc.json` becomes `typedoc.config.mjs`, which injects `basePath` from `ts-sdk/package.json`; `TS_SDK_DOCS_BASE_PATH` overrides it for root-served previews. TypeDoc probes `typedoc.json` first, so keeping both would let a bare `typedoc` silently rebuild the broken site. - `scripts/strip-remote-fonts.mjs` and `scripts/verify-deployment-paths.mjs` run as `postbuild`, the latter failing on root-relative `_assets`/`_islands` URLs, remote fonts, or a `basePath` that is not the published one. Both faults are invisible locally. - Shared logic in `scripts/deployment-checks.mjs`, covered by 18 `node:test` cases in `tests/` (no new dependencies). `breeze build-docs` now runs `npm test` too, so they run wherever docs are built. - Point the two staged-docs links in `README.md` at `airflow.staged.apache.org` rather than the raw S3 endpoint. ## Verification `npm ci && npm test && npm run build` in `ts-sdk/docs/`: ``` ℹ tests 18 ℹ pass 18 ℹ fail 0 strip-remote-fonts: removed remote font tags from 36/36 page(s). verify-deployment-paths: 36 page(s) OK (basePath "/docs/ts-sdk/0.1.0-beta1", no remote fonts). ``` Output now emits `href="/docs/ts-sdk/0.1.0-beta1/_assets/styles...css"` with no root-relative or Google Fonts references left. Rebuilding with the previous config reproduces the bug and the check exits 1 on all three counts. `TS_SDK_DOCS_BASE_PATH=/ npm run build` also passes, since root-relative URLs are correct when served from the root. A blank `TS_SDK_DOCS_BASE_PATH` falls back to the versioned prefix rather than disabling the checks, the scripts work from paths containing spaces, and remote fonts are caught in `_assets/*.css` as well as HTML. `prek --from-ref main` is clean; it also regenerates the breeze command-output hashes, which is why `dev/breeze/doc/images/` appears in the diff. --- ##### Was generative AI tooling used to co-author this PR? - [x] Yes, with help of Claude Code Opus 5 following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
