Migrate OpenFGA docs and API reference to Mintlify

[Siddhant-K-code]

Summary

Move 110 OpenFGA documentation pages and the read-only reference for 24 API operations to Mintlify, with one public mount at https://openfga.dev/docs, including /docs/api/service. Home, Project, Community, Blog, and website search remain on Docusaurus/GitHub Pages.

Use Mintlify's dashboard-provided Cloudflare Worker, not a repository-owned router. The earlier sibling /api/service deployment and custom-Worker design are superseded.

Target: docs-next; still draft. Merge and public activation remain owner-controlled. GitHub Pages must continue publishing generated output from gh-pages, not source files from docs-next. This PR has not changed DNS, Cloudflare, Mintlify, repository settings, or public traffic.

Implemented

• Flatten docs-site/docs/ into docs-site/, including all 110 articles and 35 byte-identical assets. Update navigation, links, redirects, source mappings, generators, and ownership rules. Mintlify adds the /docs mount once.
• Keep OpenAPI directory api/service; public operation URLs become /docs/api/service/.... Keep the upstream source unchanged: https://raw.githubusercontent.com/openfga/api/refs/heads/main/docs/openapiv3/apidocs.openapi.json.
• Retain /api/service as a Docusaurus fragment-aware compatibility page. Generate redirects for /api, /api-reference, and all 24 old operation URLs under both legacy prefixes. Preserve query strings, Swagger bookmarks, and encoded operation names.
• Remove deploy/, the custom Worker/router/tests/runbook, Wrangler configuration/dependency, and proxy-development/build commands. Retain read-only hosted acceptance and fingerprint/LFS checks through test:docs-deployment and verify:docs-deployment.
• Preserve the frozen content fixtures; adapt only source-location/internal-link representation when reading them. Keep the incoming parent-child guide's legacy user-groups heading target alongside #step-3.
• GHA scope: only the approved configuration updater UPDATE_FILE path correction and matching regression expectation. No branch filters, publisher logic, permissions, or API-updater fixes changed.
• Preserve original upstream commits through merge 2279221674a7f4755293276ffaaf483aaabcf89a, including feat: added dynamic conditions announcement #1372, chore(deps): bump image-size from 2.0.2 to 2.0.4 #1373, chore(deps): bump http-proxy-middleware from 2.0.9 to 2.0.10 #1374, and ci: limit blog link checks to new posts #1370. No rebasing, amended commits, or force-push.

Documentation follow-up: a2f7a7bb8e53cf2e738acdba29b0a12907ae9d40 aligns all four README guides, adds exact Cloudflare dashboard settings, separates source paths from public URLs, and documents the publication hold before merging or changing the default branch. Only READMEs and the required native-source marker changed in this follow-up.

Header follow-up: 71154abce removes the visible GitHub stars “last known” text and unused two-line styling. Only the star icon/count remain visible; cache status and observation time remain in the tooltip and accessible label. Cache expiry, native recovery, and request behavior are unchanged.

OpenAPI follow-up: ff5056776 adopts the summary/description update in openfga/api#263. All 20 paths and 24 operation identities remain unchanged; 13 summary-derived URLs change. Explicit old-to-new redirects in docs-site/docs.json preserve existing links and bookmarks. The updater now requires those redirects instead of overwriting historical aliases. Docusaurus sources, Blog content, workflows, and the SDK sample overlay are unchanged by this follow-up.

Source and URL ownership

Source or legacy URL	Public destination
docs-site/fga.mdx, navigation fga	/docs/fga
docs-site/modeling/..., navigation modeling/...	/docs/modeling/...
OpenAPI source directory api/service	/docs/api/service/...
/api/service, without a recognized Swagger fragment	/docs/api/service
/api/service#Relationship%20Queries/Check or #/Relationship%20Queries/Check	Matching new API operation
/api, /api-reference, including trailing slashes	Docusaurus compatibility entry, retaining query/fragment
/api/service/<group>/<operation> and /api-reference/<group>/<operation>	Matching /docs/api/service/<group>/<operation>, retaining query/fragment
/, /project, /community, /blog/**, website search/assets	Existing Docusaurus/GitHub Pages website
Root robots, sitemap, and LLM resources	Website-owned

HTTP cannot inspect Swagger fragments. The compatibility page therefore remains HTML, not an edge redirect. Unknown/malformed fragments produce an explicit warning and use the new API entry without looping. The page is noindex and excluded from search, sitemaps, and LLM bundles; generated aliases are redirect-only pages with canonical destinations.

Native navigation and Markdown links use source-root paths, not an extra docs/ prefix. Raw JSX anchors in reusable snippets retain explicit public URLs. Generated API pages do not require checked-in MDX files.

Preserved migration contracts

Area	Contract
Content	Preserve original visible titles, wording, page boundaries, navigation hierarchy/order, worked examples, and meaningful heading links. No editorial rewrite. Retained technical exceptions remain scoped.
API and viewers	Read-only API reference, 90 SDK samples across five languages, cURL for all 24 operations, and eight reusable native viewers. Six AuthZEN operations remain HTTP-only. Keep native tabs and the official OpenFGA DSL grammar.
Reader experience	Preserve existing typography, native navigation/search, Git-based modification dates, edit-link treatment, API descriptions, and agreed assistant-entry visibility. Keep Copy page, ChatGPT, Claude, MCP, Cursor, and VS Code actions.
Search/discovery	Separate website and Mintlify search; no unified search or dependency patch. Keep descriptions as metadata and the composite sitemap covering website pages, 110 docs, and 24 operations.
Assets	Native media stays ordinary Git during docs-next; website/Blog media stays on LFS. Both staged and working-tree native pointers are rejected.
Generated updates	Configuration updates touch only the generated region. API updates use reviewed inputs and draft-PR/issue handling, never regenerate independent fixtures or auto-merge.

Remaining owner settings

The deployment guide is the operational source of truth.

Surface	Required setting/action
GitHub repository	Coordinate docs-next as the temporary protected default/source branch; retarget contributor/updater PRs as appropriate.
GitHub Pages	Keep Deploy from a branch -> gh-pages -> / (root), custom domain openfga.dev.
Website publishing and CI	Separately approve docs-next coverage, publication hold, branch guards, and serialized publishing. Stop old main push/manual publishers from overwriting the new site. Scheduled workflows follow the default branch; an arbitrary variable is not an implemented hold.
Configuration/API updaters	Review default-branch checkout/manual-ref handling. Fix the deferred API updater's invalid job-level ${{ runner.temp }} expressions before it can run. Observed failure.
Mintlify	Existing OpenFGA project; repository openfga/openfga.dev; branch docs-next; directory /docs-site; custom domain openfga.dev; Host at /docs. Recheck edit links and deployment previews.
Cloudflare	Dashboard-generated Mintlify Worker, with routes openfga.dev/docs/*, openfga.dev/mintlify-assets/*, and openfga.dev/_mintlify/*. Preserve the existing proxied website DNS origin; no openfga.dev/*, whole-domain Worker Custom Domain, or apex CNAME takeover.
Exact /docs entry	Single Redirect matching host openfga.dev and exact path /docs, to https://openfga.dev/docs/, temporary 307, Preserve query string enabled. See the exact dashboard filter.

The root support routes remain necessary even with all content under /docs. Exact Worker patterns do not match query strings; /docs* also captures lookalike website paths. No repository-specific root /mcp, /api/request, branding-asset, or discovery rewrites remain. If provider-generated URLs escape the supported subpath/routes, resolve that with Mintlify before cutover rather than restoring a custom router.

Validation and hosted limits

Implementation validation covered the full npm run check:mintlify gate, TypeScript, scoped ESLint, production and /pr-preview/pr-1365/ website builds, and 1,125 cross-site/native links. Local Mintlify served all 24 API operations and representative articles/assets. Browser checks covered entry aliases, trailing slashes, valid/malformed Swagger fragments, queries, BatchCheck backticks, AuthZEN brackets, and leaving the website preview prefix. Redirect destinations were intercepted; these were not production acceptance requests.

All 35 relocated media files retain their original bytes and retained dependency versions/metadata are unchanged. git diff --histogram avoids misleading matching churn in the Wrangler lockfile removal. The documentation-only follow-up refreshed and checked the fingerprint and source inventory. The header follow-up passed all 71 navigation/header regressions, scoped ESLint, and fingerprint freshness; these follow-ups do not claim a new hosted or full-suite run.

The OpenAPI follow-up passed 65 targeted route/updater regressions, the full native gate, scoped ESLint, and production/preview builds with 1,125 cross-site links each. A second updater run was unchanged. This does not establish hosted acceptance of the new URLs or redirects.

Current native-source fingerprint:

ab655a379fdc6fe3d305e6cf78b73f4b1a4ef4356950def4d69a6f6cdf280aa6

The configured hosted deployment and public Worker have not been accepted for this fingerprint. Local previews use source-root routes and cannot establish hosted canonical, discovery, search, or MCP correctness. Previous two-prefix/proxy evidence is superseded.

Release gates and recovery

• Obtain documentation/frontend/DX reviews. CODEOWNERS in the PR base controls automatic assignment until these ownership changes are merged.
• Record disposition of existing dependency license-policy warnings.
• Name cutover/rollback owners, save previous website/edge/provider settings, and hold push, scheduled, manual, already-running, and queued publishers before merging or switching the default branch.
• Merge the reviewed state into docs-next, configure Mintlify's /docs mount, and accept the matching hosted fingerprint. Do not publish the docs-free Docusaurus build yet.
• Activate the scoped provider Worker routes and exact-entry redirect, then publish the matching Docusaurus build in the agreed window.
• Complete public acceptance of docs/API pages, old bookmarks, website routes, assets, canonical URLs, discovery, search, and MCP/editor actions.

# After Mintlify deploys the configured /docs mount from the selected checkout:
npm run verify:docs-origin

# After coordinated public activation and website publication:
npm run verify:docs-deployment -- --origin https://openfga.dev

Mintlify-only staging stops after native acceptance, without changing public routing or publishing the migrated website. See the ordered release sequence.

Rollback requires the complete previous website and its corresponding edge/provider configuration; removing docs routes alone leaves documentation unavailable. When Mintlify LFS support is verified end-to-end, apply the accepted migration onto a fresh branch from current main, convert native media to LFS before integration commits, and switch default/Mintlify/publisher/updater targets together. Do not import temporary inline-asset ancestry wholesale or assume skipping one conversion commit removes every ordinary-Git asset.

[Copilot]

Copilot review overview

🟡 Changes recommended

The relocated Community page introduces unapproved editorial drift despite the migration’s explicit content-preservation contract.

Review effort: Balanced
Findings: 1

Open (1)

• Community page migration changes legacy copy · New

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-28 08:15 UTC