| type | Reference | |||||
|---|---|---|---|---|---|---|
| title | Documentation site maintenance | |||||
| description | Canonical maintenance for docs.page (docs.json) and TypeDoc (reference.rnfirebase.io), including legacy redirect audits and the docs.page link check in CI. | |||||
| tags |
|
|||||
| timestamp | 2026-07-02 00:00:00 UTC |
Single source for user-facing documentation site maintenance: docs.page content under docs/ plus docs.json, and the TypeDoc reference site at reference.rnfirebase.io.
Policy: OKF documentation and commit policy.
| Site | Config | Output / host |
|---|---|---|
| User docs (rnfirebase.io) | docs.json + docs/** |
docs.page |
| API reference | typedoc.json (+ per-package packages/*/typedoc.json) |
yarn reference:api → reference/; published at reference.rnfirebase.io |
When Publish deploys the API reference (main-only), see maintainer publish.
Pre–docs.page API pages lived under /reference/... on the old Gatsby site (website/public/reference/**). docs.json redirects maps those paths to the current TypeDoc URLs so bookmarks and external links keep working.
Redirect keys are path-only (no leading slash), e.g. reference/auth/user.
When mapping or auditing redirects, generated paths follow these patterns (base: https://reference.rnfirebase.io/):
| Kind | Pattern |
|---|---|
| Module index | _react-native-firebase/{package}.html |
| Auth types | _react-native-firebase/auth/FirebaseAuthTypes/{Type}.html |
| Auth functions | _react-native-firebase/auth/{functionName}.html |
| Package types namespace | _react-native-firebase/{package}/types/{package}/{Type}.html |
| Firestore modular exports | _react-native-firebase/firestore/modular/{Export}.html |
| Storage types | _react-native-firebase/storage/{Type}.html |
| Module listing | modules.html |
Names are PascalCase and may differ from legacy lowercase paths (e.g. oidcprovider → OAuthProvider, settings → FirestoreSettings, reference → StorageReference / DatabaseReference).
Removed packages (e.g. Dynamic Links) have no TypeDoc module — fall back to modules.html or the closest surviving type.
Trigger: any edit to typedoc.json, packages/*/typedoc.json, or TypeDoc-related scripts/options that can change reference URL structure — including:
router,entryPoints,entryPointStrategy,outnavigation,categorizeByGroup,sortEntryPoints,groupOrder- package renames, module removal, or export surface moves that change generated page paths
Not required for JSDoc-only edits that do not change TypeDoc options or exported symbols.
- Regenerate locally:
yarn reference:api(afteryarn tsc:compile:consumerif needed). - Verify existing redirects: every target URL in
docs.json→redirectsmust return HTTP 200 on the published site (or on localreference/output if pre-deploy). Fix broken mappings before merge. - Scan for new orphans: compare legacy paths under
website/public/reference/**(or inbound/reference/...links in the repo) against currentredirectskeys. Add entries for any legacy path not yet covered. - Spot-check renames: module/type renames often change TypeDoc filenames — update redirect values, not only keys.
- Document durable renames in this file or package OKF docs when non-obvious (e.g. analytics refund event type renamed to
RefundEventParameters).
-
yarn reference:apisucceeds - All
docs.jsonredirect targets verified (200) - New legacy paths identified and redirected or explicitly deferred with rationale
- Docs checks (
yarn lint:markdown,yarn lint:spellcheck,yarn docs:tsc:check,yarn docs:member:check,yarn lint:docs-links) whendocs/**or docs tooling changed: validation checklist § lint and formatting (docs row and § docs lint gotchas; OKF-only diffs do not run those). Missinglint:docs-linksevidence whendocs/**was touched is serious (change authoring § work types)
Validation commands: validation checklist § API reference, § lint and formatting.
yarn lint:docs-links runs @docs.page/cli check (pinned in root package.json, ≥ 2.2.0 for per-host severity overrides) and is a step in .github/workflows/docs.yml, wrapped in nick-fields/retry to absorb transient external failures (5xx, timeouts); a real breakage fails every attempt. The yarn script is docs check . — CLI defaults plus the docs.json check block; no severity flags on the command line. Fresh CLI publishes younger than the repo npmMinimalAgeGate (7d) must be listed in .yarnrc.yml npmPreapprovedPackages.
Severity: external 404, 5xx, DNS, and timeout failures are errors. Bot-gated HTTP statuses (401 / 403 / 405 / 429) are warnings so CI stays green while still surfacing hosts that refuse automated clients (npmjs, Stack Overflow, and similar). Do not add --external-links warn or --ignore-external-hosts — that would hide TypeDoc rot on reference.rnfirebase.io.
Host overrides: docs.json check.severityOverrideHosts pins rnfirebase.io to error. Matching includes subdomains, so reference.rnfirebase.io is covered, and the override applies to every failure — bot-gate statuses included — so a rate-limited or broken TypeDoc link cannot downgrade to a warning. Do not add warn overrides for first-party hosts; add an error entry when another first-party host must never downgrade.
What agents must fix vs may leave: validation checklist § docs.page link check.
When adding user docs pages only (sidebar, tabs, content under docs/):
- Add sidebar entries in
docs.jsonwhen new pages ship. - Run markdown/spellcheck/link check per validation checklist:
yarn lint:markdown,yarn lint:spellcheck,yarn lint:docs-links. - Redirect audit not required unless
redirectsor TypeDoc config also changed.
typedoc.json is parsed as JSONC by TypeDoc (comments and trailing commas allowed). A short comment at the top of that file points here — see TypeDoc configuration options.
TypeDoc accepts configuration from several formats (TypeDoc configuration docs):
| Format | File names | Comments |
|---|---|---|
| JSONC (recommended here) | typedoc.json, typedoc.jsonc |
// and /* */ — typedoc.json is parsed as JSONC, same as tsconfig.json |
| JavaScript | typedoc.config.mjs, .cjs, .js |
Block comments + @type JSDoc on exports |
| Embedded | package.json / tsconfig.json → typedocOptions |
Strict JSON only — no comments |
Recommendation: keep typedoc.json and add JSONC comments for maintainer warnings (redirect audit trigger). Use typedoc.config.mjs only if config logic must be programmatic.
Note: strict JSON validators (e.g. python -m json.tool) reject comments — use TypeDoc or editor JSONC support to validate config, not generic JSON parsers.