feat(fga): POC — Docusaurus to Mintlify migration as fga/ microsite

[nick-gagliardi]

Summary

POC for migrating the FGA docs from Docusaurus (atko-cic/fga-docs) to Mintlify, landing as a new self-contained fga/ microsite alongside main/ and auth4genai/. Final URL target: docs.fga.dev.

10 representative pages were converted, chosen to exercise every Docusaurus-ism we'll hit when migrating the remaining 78 pages.

What's in the POC

• fga/docs.json — Mintlify config modeled on auth4genai/docs.json, Auth0 orange palette, 5 redirects ported from docusaurus.config.js
• 10 converted MDX pages across 5 nav groups (Introduction, Getting started, Modeling, API integration, Migrations & notices)
• 3 snippet components in fga/snippets/:
  • CheckRequestViewer.jsx — fully ported, generates SDK code for 9 languages from props
  • AuthzModelSnippetViewer.jsx — JSON-only port (DSL pending — see notes)
  • SupportedLanguage.jsx — shared constants
• 24 image assets + 2 logo SVGs
• fga/scripts/convert.mjs — five-pass regex converter (imports, admonitions, tabs, frontmatter, branding helpers)
• fga/scripts/cleanup.mjs — idempotent post-process (Tip placeholders for unported viewers, HTML comment stripping, viewer import injection)
• fga/MIGRATION_NOTES.md — patterns documented for the team to apply to the remaining 78 pages

Conversion patterns validated

Source	Target	Status
:::note/info/tip/caution/warning/danger	<Note>/<Info>/<Tip>/<Warning>	Mechanical (regex)
<Tabs groupId> + <TabItem value label>	<Tabs> + <Tab title>	Mechanical (regex)
<ProductName format={...}/>	Static "Auth0 FGA" / "Auth0 Fine Grained Authorization"	Mechanical
<ProductConcept section linkName/>	Markdown link to /intro/fga-concepts#section	Mechanical
<UpdateProductNameInLinks link name/>	Plain markdown link	Mechanical
Docusaurus frontmatter (sidebar_position, slug)	Mintlify (permalink)	Mechanical
@site/static/img/foo.svg SVG-as-component	<img src="/img/foo.svg">	Mechanical
./assets/foo.png and variants	/img/foo.png	Mechanical
<RelatedSection relatedLinks={[...]}/>	<CardGroup> of <Card>	Manual (~5 min/page)
9 SDK viewer types	fga/snippets/*.jsx	2/9 ported, 7 placeholders

Known limitations

1. AuthzModelSnippetViewer renders JSON, not DSL. The original uses @openfga/syntax-transformer for JSON→DSL conversion; bundling that into Mintlify's snippet runtime is a follow-up. Pages that pass syntaxesToShow={[SyntaxFormat.Dsl]} show JSON with a note. The component accepts an optional dsl prop for pre-computed DSL strings.
2. 7 viewer types are stubbed as <Tip> placeholders: BatchCheckRequestViewer, WriteRequestViewer, ListObjectsRequestViewer, ListUsersRequestViewer, ReadChangesRequestViewer, ExpandRequestViewer, RelationshipTuplesViewer. Porting pattern documented in MIGRATION_NOTES.md.
3. 71 broken internal links remain — all to pages outside the POC subset (e.g. ./configuration-language, ./parent-child.mdx). They resolve once those pages migrate.

Test plan

• Run cd fga && mint dev — disable VPN on first run per docs-v2/CLAUDE.md
• Walk all 10 pages, confirm sidebar matches docs.json (5 groups)
• Verify <Tabs> switching on getting-started/perform-check and migration-instructions
• Verify all admonition flavors render (<Note>, <Info>, <Tip>, <Warning>)
• Confirm images load on getting-started/new-getting-started and inline SVGs render on modeling/getting-started
• Confirm ported <CheckRequestViewer> shows tabs for all 9 languages with correct generated code on getting-started/perform-check
• Confirm <AuthzModelSnippetViewer> renders JSON on modeling/direct-access (and shows the JSON-fallback message for DSL views)
• Test all 5 redirects resolve correctly
• mint broken-links — already validated locally (0 parse errors, 71 broken links to non-POC pages)

Open items (not blocking POC)

• Confirm Auth0 orange palette is right or pick an FGA-specific palette
• auth4genai/mcp/get-started/secure-mcp-server-with-auth0-fga.mdx stays put; cross-link from there to this microsite once live
• Mintlify project + docs.fga.dev DNS setup is out of scope

[github-actions]

Summary

Status	Count
🔍 Total	198
✅ Successful	37
⏳ Timeouts	0
🔀 Redirected	13
👻 Excluded	147
❓ Unknown	0
🚫 Errors	1
⛔ Unsupported	0

Errors per input

Errors in fga/getting-started/new-getting-started.mdx

• [401] https://api.us1.fga.dev/ | Rejected status code (this depends on your "accept" configuration): Unauthorized

Redirects per input

Redirects in fga/getting-started/new-getting-started.mdx

• [200] https://fga.dev/ | Redirect: Followed 2 redirects resolving to the final status of: OK. Redirects: https://fga.dev/ --> https://auth0.com/developers/lab/fine-grained-authorization --> https://auth0.com/fine-grained-authorization
• [200] https://zanzibar.academy/ | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://zanzibar.academy/ --> https://www.zanzibar.academy/

Redirects in fga/interacting/managing-user-access.mdx

• [200] https://openfga.dev/docs | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://openfga.dev/docs --> https://openfga.dev/docs/

Redirects in fga/intro/about-auth0-fga.mdx

• [200] https://zanzibar.academy/ | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://zanzibar.academy/ --> https://www.zanzibar.academy/

Redirects in fga/intro/authorization-concepts.mdx

• [200] https://research.google/pubs/pub48190/ | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://research.google/pubs/pub48190/ --> https://research.google/pubs/zanzibar-googles-consistent-global-authorization-system/
• [200] https://zanzibar.academy/ | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://zanzibar.academy/ --> https://www.zanzibar.academy/

Redirects in fga/intro/fga-concepts.mdx

• [200] https://github.com/google/cel-spec | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://github.com/google/cel-spec --> https://github.com/cel-expr/cel-spec
• [200] https://openfga.dev/docs | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://openfga.dev/docs --> https://openfga.dev/docs/
• [200] https://research.google/pubs/pub48190/ | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://research.google/pubs/pub48190/ --> https://research.google/pubs/zanzibar-googles-consistent-global-authorization-system/

Redirects in fga/migration-instructions.mdx

• [200] https://auth.fga.dev/ | Redirect: Followed 3 redirects resolving to the final status of: OK. Redirects: https://auth.fga.dev/ --> https://fga.dev/ --> https://auth0.com/developers/lab/fine-grained-authorization --> https://auth0.com/fine-grained-authorization

Redirects in fga/modeling/direct-access.mdx

• [200] https://openfga.dev/docs | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://openfga.dev/docs --> https://openfga.dev/docs/

Redirects in fga/modeling/getting-started.mdx

• [200] https://openfga.dev/docs | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://openfga.dev/docs --> https://openfga.dev/docs/

Redirects in fga/modeling/user-groups.mdx

• [200] https://openfga.dev/docs | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://openfga.dev/docs --> https://openfga.dev/docs/
  Full Github Actions output