ci(docs): add docs.page link check to docs workflow by mikehardy · Pull Request #9214 · invertase/react-native-firebase

mikehardy · 2026-08-22T23:17:43Z

Summary

Integrates @docs.page/cli check into RNFB docs validation so broken internal links, missing assets, MDX render issues, and metadata problems fail CI — closing the gap left after the June 2026 link-audit sweep (PR #9051), which fixed URLs but never wired the checker into lint/CI.

Two bisectable commits:

docs sweep — fix broken TypeDoc/reference URLs and metadata (migrating-to-v26.mdx em dash) so the checker is green before enforcement lands
CI integration — yarn lint:docs-links (docs check .), @docs.page/cli@2.1.0, .github/workflows/docs.yml step, OKF agent guidance (bot-gate warns; real 404s error)

External links

docs check . uses CLI defaults. Real breakage (404, 5xx, DNS, timeout) fails CI. Bot-gated hosts (401 / 403 / 405 / 429) warn for visibility without false-positive red builds. Agents still must fix every error line (validation-checklist § docs.page link check).

Test plan

yarn lint:markdown exit 0
yarn lint:spellcheck exit 0
yarn lint:docs-links exit 0 against @docs.page/cli@2.1.0 (0 errors; bot-gate 403s as warnings)
Docs workflow green on CI after push

Maintainer note: Fixes CPRN-368

codecov · 2026-08-22T23:44:02Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.50%. Comparing base (a4270af) to head (408de77).
⚠️ Report is 21 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #9214   +/-   ##
=========================================
  Coverage     69.50%   69.50%           
- Complexity     2124     2125    +1     
=========================================
  Files           443      443           
  Lines         25536    25536           
  Branches       4259     4259           
=========================================
  Hits          17745    17745           
  Misses         6389     6389           
  Partials       1402     1402

Flag	Coverage Δ
android-native	`65.85% <ø> (ø)`
e2e-ts-android	`54.17% <ø> (ø)`
e2e-ts-ios	`53.64% <ø> (ø)`
e2e-ts-macos	`49.88% <ø> (ø)`
ios-ruby	`100.00% <ø> (ø)`
jest	`47.72% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

russellwheatley

Two things before merge. The AuthSettings fragment drop is a real docs regression. The TypeDoc host gap is bigger: with the current CLI, this job will not fail on a broken reference.rnfirebase.io URL after merge.

russellwheatley · 2026-08-24T12:43:47Z

 Ensure that all parts of step 1 and 2 from [the official firebase Android phone auth docs](https://firebase.google.com/docs/auth/android/phone-auth#enable-phone-number-sign-in-for-your-firebase-project) have been followed.

-To bypass Play Integrity for manual testing, you may [force reCAPTCHA to be used](https://reference.rnfirebase.io/_react-native-firebase/auth/FirebaseAuthTypes/AuthSettings.html#appVerificationDisabledForTesting) prior to calling [`verifyPhoneNumber`](https://reference.rnfirebase.io/_react-native-firebase/auth/verifyPhoneNumber.html).
+To bypass Play Integrity for manual testing, you may [force reCAPTCHA to be used](https://reference.rnfirebase.io/_react-native-firebase/auth/AuthSettings.html) prior to calling [`verifyPhoneNumber`](https://reference.rnfirebase.io/_react-native-firebase/auth/verifyPhoneNumber.html).


The iOS AuthSettings link a few lines up still deep-links to #appverificationdisabledfortesting. This Android one dropped the fragment, so it lands on the interface page instead of the property. Restore the same hash.

Restored. Both the iOS and Android AuthSettings links now use #appverificationdisabledfortesting on the live TypeDoc page (AuthSettings.html). That hash lives in the sweep commit (docs: fix broken links found by docs.page check) so the first commit is already click-correct.

russellwheatley · 2026-08-24T12:43:47Z

    "lint:ios:check": "find packages/*/ios -type f \\( -name '*.h' -o -name '*.cpp' -o -name '*.m' -o -name '*.mm' \\) -not -path '*/generated/*' -print0 | xargs -0 clang-format --style=Google -n -Werror",
    "lint:ios:fix": "find packages/*/ios -type f \\( -name '*.h' -o -name '*.cpp' -o -name '*.m' -o -name '*.mm' \\) -not -path '*/generated/*' -print0 | xargs -0 clang-format -i --style=Google",
    "lint:markdown": "eslint \"docs/**/*.mdx\" --max-warnings=0 && prettier --check \"docs/**/*.mdx\"",
+    "lint:docs-links": "docs check . --external-links warn",


--external-links warn is the right call for npm/SO 403s. @docs.page/cli treats every https:// URL as external (classifyTarget), and there is no per-host severity. That means a 404 on reference.rnfirebase.io will only warn, which is almost every TypeDoc link this sweep rewrote.

Internal /auth/usage paths, assets, MDX, and frontmatter will still fail the job. TypeDoc URL rot will not.

If the point of wiring this in is to keep those reference links honest, this needs a companion check that fails on that host, or a CLI feature for host-specific severity. As written, the sweep helps today's clicks and then CI stops watching.

Agreed — with the current CLI, https://reference.rnfirebase.io/... is classified as external, so --external-links warn will not fail the job on TypeDoc 404s.

We are leaving this as-is until @docs.page/cli grows host-specific severity (or equivalent). This PR is converted to draft until that lands; then we can make reference.rnfirebase.io fail CI without also failing on npm/SO 403s.

invertase/docs.page#544 is in progress

mikehardy · 2026-09-02T12:03:41Z

blocked: do-not-merge — waiting on final merge + publish of invertase/docs.page#544.

This PR is already shaped as if that release is live (docs check ., bot-gate statuses as warnings, real 404s still errors). Once #544 ships on npm, bump @docs.page/cli here and we are unblocked.

russellwheatley

Two things again before this can land + CI failure needs resolving.

russellwheatley · 2026-09-04T12:43:31Z

 # In case you must have a package version that would be disallowed
 # by the above npmMinimalAgeGate
 npmPreapprovedPackages:
+  - '@docs.page/cli@2.1.0' # published 2026-09-04; needed immediately for docs CI


The reference.rnfirebase.io gap is still there. 2.1.0 treats 401/403/405/429 as warnings on every host, and nothing here pins reference.rnfirebase.io back to hard-error. That host isn't bot-gated today, but if Cloudflare/Fastly ever 429s it under the burst of requests this check fires, a real broken TypeDoc link would quietly become a warning instead of failing the build, which is the whole thing this PR is meant to catch.

That's a good one and it's handled poorly - I've pursuing upstream CLI remediation/features that will stop conflating "bot blocked" vs "failed but should have worked" so we don't downgrade things we want. Upstream pursuit:

debug flag and better error messaging for better error tracing in case of problems

ability to specify explicit hosts we know are bot-friendly so never downgrade

friendly server behavior so cloudflare or others don't 429 us (honoring retry-after, less per-host concurrent load etc)

This whole PR should sit again until those are resolved - this exercise is making the docs.page CLI checker a lot more battle-tested that's for sure!

russellwheatley · 2026-09-04T12:43:31Z

        run: |
          yarn lint:spellcheck
+      - name: Docs.page links
+        run: yarn lint:docs-links


This check is already flaky on this exact commit. Same head SHA, two runs: one failed on invertase.io/blog/... with "operation was aborted" (timeout), the other passed clean with 0 errors. I hit that blog URL directly a few times just now and it's fine, so this looks like a transient network hiccup, not a real 404, and there's no retry around it (Yarn Install a few lines up already wraps itself in nick-fields/retry). As-is this will occasionally fail PRs for no reason.

comment above should work to handle this

Superseded by #9214 (review) - AuthSettings fragment looks fixed on the current commits, TypeDoc host-gap point carried forward there along with a new flakiness finding.

mikehardy · 2026-09-04T15:26:34Z

Back to draft for a bit while newly surfaced production-usage issues get some clean upstream solutions

Details: #9214 (comment)

mikehardy requested a review from russellwheatley August 22, 2026 23:17

russellwheatley previously requested changes Aug 24, 2026

View reviewed changes

mikehardy marked this pull request as draft August 26, 2026 13:09

mikehardy force-pushed the docs-page-link-check-ci branch from f015cec to 106d170 Compare August 26, 2026 13:09

claude Bot mentioned this pull request Sep 1, 2026

feat(cli): support ignoring external hosts invertase/docs.page#544

Merged

13 tasks

mikehardy force-pushed the docs-page-link-check-ci branch from 106d170 to 2e4dca3 Compare September 2, 2026 12:02

mikehardy added the blocked: do-not-merge Do not merge this issue without approval by the person who labelled this issue as Do Not Merge label Sep 2, 2026

github-actions Bot added the Needs Attention label Sep 2, 2026

docs: fix broken links found by docs.page check

d05ba01

mikehardy marked this pull request as ready for review September 4, 2026 11:33

mikehardy force-pushed the docs-page-link-check-ci branch from 2e4dca3 to 9b251ab Compare September 4, 2026 11:33

mikehardy removed the blocked: do-not-merge Do not merge this issue without approval by the person who labelled this issue as Do Not Merge label Sep 4, 2026

ci(docs): add docs.page link check to docs workflow

408de77

mikehardy force-pushed the docs-page-link-check-ci branch from 9b251ab to 408de77 Compare September 4, 2026 11:37

russellwheatley requested changes Sep 4, 2026

View reviewed changes

mikehardy marked this pull request as draft September 4, 2026 15:25

Uh oh!

Conversation

mikehardy commented Aug 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

External links

Test plan

Uh oh!

codecov Bot commented Aug 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

russellwheatley left a comment

Choose a reason for hiding this comment

Uh oh!

russellwheatley Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikehardy Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

russellwheatley Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikehardy Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

mikehardy Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mikehardy commented Sep 2, 2026

Uh oh!

russellwheatley left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

russellwheatley Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

mikehardy Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

russellwheatley Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

mikehardy Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

mikehardy commented Sep 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mikehardy commented Aug 22, 2026 •

edited

Loading

codecov Bot commented Aug 22, 2026 •

edited

Loading

russellwheatley Aug 24, 2026 •

edited

Loading

russellwheatley Aug 24, 2026 •

edited

Loading

russellwheatley left a comment •

edited

Loading