docs: migrate kratos passwordless, mfa, and debug docs to deployment structure#2675
docs: migrate kratos passwordless, mfa, and debug docs to deployment structure#2675hperl wants to merge 9 commits into
Conversation
Shared partials under src/components/Shared/kratos/passwordless with Network and OEL shell pages, per the migration pattern in AGENTS.md. Part of #2674. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Shared partials under src/components/Shared/kratos/mfa with Network and OEL shell pages; the previously half-migrated MFA overview partial is refreshed from the newer co-mingled page, which is removed. Part of #2674. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Network sidebar uses the network shells; the OEL sidebar gains an Authentication category so self-hosted readers keep OEL navigation context (#2674). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
SameDeploymentLink keeps readers in their deployment; the welcome page cards point at the Network shells. Part of #2674. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The shared kratos MFA overview partial is imported by the OSS deployment shell, but the migration created MFA/passwordless sub-page shells only for Network and OEL. On OSS the SameDeploymentLink targets resolved to non-existent /docs/oss/kratos/... pages, producing broken links. Add oss= overrides pointing to the Network pages (matching the OSS shell canonical and the vercel.json redirects). Network/OEL behaviour is unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Prettier's 80-column reflow orphaned "Go to" as its own paragraph before the ConsoleLink tags; reword so the tags stay mid-line. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR migrates Ory Kratos passwordless and MFA documentation into the per-deployment “shell + shared partial” structure so that Ory Network and OEL readers keep stable, deployment-specific sidebar navigation while sharing the same page bodies.
Changes:
- Moved passwordless + MFA page bodies into shared partials under
src/components/Shared/kratos/...and added thin shell pages underdocs/network/...anddocs/oel/...with Network canonicals. - Updated Network and OEL sidebars to point at the new deployment shell doc IDs (and added an OEL “Authentication” category).
- Updated internal links and Vercel redirects to point old URLs to the new Network routes and reduce redirect chaining.
Reviewed changes
Copilot reviewed 43 out of 64 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| vercel.json | Retargets existing redirects and adds new ones from legacy kratos passwordless/MFA URLs to Network deployment URLs. |
| src/pages/_assets/welcome-content.tsx | Updates homepage “docs” links to the new Network deployment routes for passkeys/OTP/MFA overview. |
| src/components/Shared/kratos/passwordless/07_code.mdx | Converts passwordless OTP page into a shared partial (no frontmatter) and updates links to stable doc routes. |
| src/components/Shared/kratos/passwordless/06_passkeys-mobile.mdx | Converts passkeys mobile guide into a shared partial and updates cross-page links to deployment-aware links. |
| src/components/Shared/kratos/passwordless/05_passkeys.mdx | Converts passkeys overview into a shared partial and updates image/link paths for the new shared location. |
| src/components/Shared/kratos/passwordless/00_overview.mdx | Adds new shared partial for passwordless overview content. |
| src/components/Shared/kratos/passwordless/_static/ax-registration-code.png | Adds static asset under shared passwordless partials. |
| src/components/Shared/kratos/mfa/30_sms.mdx | Converts MFA via SMS/email into a shared partial and updates links/image paths. |
| src/components/Shared/kratos/mfa/25_lookup-secrets.mdx | Converts lookup secrets page into a shared partial and updates image paths. |
| src/components/Shared/kratos/mfa/20_webauthn-fido-yubikey.mdx | Converts WebAuthn MFA page into a shared partial and updates links/image paths. |
| src/components/Shared/kratos/mfa/15_totp.mdx | Converts TOTP MFA page into a shared partial and updates image paths. |
| src/components/Shared/kratos/mfa/05_step-up-authentication.mdx | Converts step-up auth page into a shared partial and updates links to stable API/doc routes. |
| src/components/Shared/kratos/01_mfa-overview.mdx | Refreshes shared MFA overview and switches internal links to SameDeploymentLink with OSS overrides. |
| sidebars-oel.ts | Adds an “Authentication” category listing OEL shells for passwordless and MFA content. |
| sidebars-network.ts | Switches Network sidebar entries from co-mingled doc IDs to Network deployment shell doc IDs. |
| docs/oel/kratos/passwordless/07_code.mdx | Adds OEL shell page for passwordless OTP, importing the shared partial and setting canonical to Network. |
| docs/oel/kratos/passwordless/06_passkeys-mobile.mdx | Adds OEL shell page for passkeys mobile, importing shared partial and setting canonical to Network. |
| docs/oel/kratos/passwordless/05_passkeys.mdx | Adds OEL shell page for passkeys overview, importing shared partial and setting canonical to Network. |
| docs/oel/kratos/passwordless/00_overview.mdx | Adds OEL shell page for passwordless overview, importing shared partial and setting canonical to Network. |
| docs/oel/kratos/mfa/30_sms.mdx | Adds OEL shell page for SMS/email MFA, importing shared partial and setting canonical to Network. |
| docs/oel/kratos/mfa/25_lookup-secrets.mdx | Adds OEL shell page for lookup secrets, importing shared partial and setting canonical to Network. |
| docs/oel/kratos/mfa/20_webauthn-fido-yubikey.mdx | Adds OEL shell page for WebAuthn MFA, importing shared partial and setting canonical to Network. |
| docs/oel/kratos/mfa/15_totp.mdx | Adds OEL shell page for TOTP MFA, importing shared partial and setting canonical to Network. |
| docs/oel/kratos/mfa/05_step-up-authentication.mdx | Adds OEL shell page for step-up authentication, importing shared partial and setting canonical to Network. |
| docs/network/kratos/passwordless/07_code.mdx | Adds Network shell page for passwordless OTP, importing shared partial and self-canonicalizing. |
| docs/network/kratos/passwordless/06_passkeys-mobile.mdx | Adds Network shell page for passkeys mobile, importing shared partial and self-canonicalizing. |
| docs/network/kratos/passwordless/05_passkeys.mdx | Adds Network shell page for passkeys overview, importing shared partial and self-canonicalizing. |
| docs/network/kratos/passwordless/00_overview.mdx | Adds Network shell page for passwordless overview, importing shared partial and self-canonicalizing. |
| docs/network/kratos/mfa/30_sms.mdx | Adds Network shell page for SMS/email MFA, importing shared partial and self-canonicalizing. |
| docs/network/kratos/mfa/25_lookup-secrets.mdx | Adds Network shell page for lookup secrets, importing shared partial and self-canonicalizing. |
| docs/network/kratos/mfa/20_webauthn-fido-yubikey.mdx | Adds Network shell page for WebAuthn MFA, importing shared partial and self-canonicalizing. |
| docs/network/kratos/mfa/15_totp.mdx | Adds Network shell page for TOTP MFA, importing shared partial and self-canonicalizing. |
| docs/network/kratos/mfa/05_step-up-authentication.mdx | Adds Network shell page for step-up authentication, importing shared partial and self-canonicalizing. |
| docs/kratos/social-signin/93_upstream-mfa.mdx | Updates references to step-up auth to use SameDeploymentLink. |
| docs/kratos/self-service/flows/verify-email-account-activation.mdx | Updates TOTP/WebAuthn links to use SameDeploymentLink list items. |
| docs/kratos/self-service/flows/user-login.mdx | Updates passkey/code links to new deployment-aware targets via SameDeploymentLink. |
| docs/kratos/passwordless/00_overview.mdx | Removes the old co-mingled passwordless overview page after migrating content to shared + deployment shells. |
| docs/kratos/mfa/01_overview.mdx | Removes the old co-mingled MFA overview page after migrating content to shared + deployment shells. |
| docs/kratos/guides/deploy-kratos-example.mdx | Updates MFA guide link to SameDeploymentLink (deployment-aware). |
| docs/kratos/emails-sms/05_custom-email-templates.mdx | Updates one-time-code docs links to SameDeploymentLink. |
| docs/integrates-with/mfa/yubikey.mdx | Updates canonical to Network and replaces direct link with SameDeploymentLink. |
| docs/integrates-with/mfa/okta-verify.mdx | Updates WebAuthn MFA reference to SameDeploymentLink. |
| docs/integrates-with/mfa/duo-security.mdx | Updates WebAuthn MFA reference to SameDeploymentLink. |
| docs/getting-started/local-development.mdx | Updates WebAuthn reference to SameDeploymentLink. |
Comments suppressed due to low confidence (2)
src/components/Shared/kratos/mfa/25_lookup-secrets.mdx:60
- Typo in the admonition text: “secretes” should be “secrets”.
src/components/Shared/kratos/mfa/30_sms.mdx:14 - Use “cannot” (one word) and capitalize “SMS” for consistency with the rest of the page.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
📝 WalkthroughWalkthroughKratos passwordless, MFA, and debug documentation are reorganized under deployment-specific paths, with updated sidebar entries, landing-page links, troubleshooting content, and permanent redirects from legacy URLs. ChangesKratos documentation paths
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@vercel.json`:
- Line 1527: Add a Vercel redirect rule for the legacy
`/docs/kratos/passwordless/07_code` path, targeting
`/docs/network/kratos/passwordless/one-time-code`, alongside the existing
passwordless redirect entries in vercel.json.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 8214fd42-f441-4db1-8f8d-8b3a20fa6dd3
⛔ Files ignored due to path filters (60)
docs/getting-started/local-development.mdxis excluded by!**/*.mdxdocs/integrates-with/mfa/duo-security.mdxis excluded by!**/*.mdxdocs/integrates-with/mfa/okta-verify.mdxis excluded by!**/*.mdxdocs/integrates-with/mfa/yubikey.mdxis excluded by!**/*.mdxdocs/kratos/emails-sms/05_custom-email-templates.mdxis excluded by!**/*.mdxdocs/kratos/guides/deploy-kratos-example.mdxis excluded by!**/*.mdxdocs/kratos/mfa/01_overview.mdxis excluded by!**/*.mdxdocs/kratos/passwordless/00_overview.mdxis excluded by!**/*.mdxdocs/kratos/self-service/flows/user-login.mdxis excluded by!**/*.mdxdocs/kratos/self-service/flows/verify-email-account-activation.mdxis excluded by!**/*.mdxdocs/kratos/social-signin/93_upstream-mfa.mdxis excluded by!**/*.mdxdocs/network/kratos/mfa/05_step-up-authentication.mdxis excluded by!**/*.mdxdocs/network/kratos/mfa/15_totp.mdxis excluded by!**/*.mdxdocs/network/kratos/mfa/20_webauthn-fido-yubikey.mdxis excluded by!**/*.mdxdocs/network/kratos/mfa/25_lookup-secrets.mdxis excluded by!**/*.mdxdocs/network/kratos/mfa/30_sms.mdxis excluded by!**/*.mdxdocs/network/kratos/passwordless/00_overview.mdxis excluded by!**/*.mdxdocs/network/kratos/passwordless/05_passkeys.mdxis excluded by!**/*.mdxdocs/network/kratos/passwordless/06_passkeys-mobile.mdxis excluded by!**/*.mdxdocs/network/kratos/passwordless/07_code.mdxis excluded by!**/*.mdxdocs/oel/kratos/mfa/05_step-up-authentication.mdxis excluded by!**/*.mdxdocs/oel/kratos/mfa/15_totp.mdxis excluded by!**/*.mdxdocs/oel/kratos/mfa/20_webauthn-fido-yubikey.mdxis excluded by!**/*.mdxdocs/oel/kratos/mfa/25_lookup-secrets.mdxis excluded by!**/*.mdxdocs/oel/kratos/mfa/30_sms.mdxis excluded by!**/*.mdxdocs/oel/kratos/passwordless/00_overview.mdxis excluded by!**/*.mdxdocs/oel/kratos/passwordless/05_passkeys.mdxis excluded by!**/*.mdxdocs/oel/kratos/passwordless/06_passkeys-mobile.mdxis excluded by!**/*.mdxdocs/oel/kratos/passwordless/07_code.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/01_mfa-overview.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/mfa/05_step-up-authentication.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/mfa/15_totp.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/mfa/20_webauthn-fido-yubikey.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/mfa/25_lookup-secrets.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/mfa/30_sms.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/mfa/_static/1.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/10.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/11.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/2.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/3.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/4.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/5.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/6.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/7.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/8.pngis excluded by!**/*.pngsrc/components/Shared/kratos/mfa/_static/9.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/00_overview.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/passwordless/05_passkeys.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/passwordless/06_passkeys-mobile.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/passwordless/07_code.mdxis excluded by!**/*.mdxsrc/components/Shared/kratos/passwordless/_static/ax-login-options.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/_static/ax-login-options2.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/_static/ax-registration-code.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/_static/external-device-choose.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/_static/external-device-verify-identity.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/_static/passkeys/console.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/_static/passwordless-login-flow.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/_static/webauthn/1.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/_static/webauthn/2.pngis excluded by!**/*.pngsrc/components/Shared/kratos/passwordless/_static/webauthn/3.pngis excluded by!**/*.png
📒 Files selected for processing (4)
sidebars-network.tssidebars-oel.tssrc/pages/_assets/welcome-content.tsxvercel.json
Add a redirect for the legacy /docs/kratos/passwordless/07_code URL (orphaned since the page received its explicit one-time-code id) and fix two typos in the moved MFA partials. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The debug pages were autogenerated into both the OEL and OSS sidebars, so one deployment always hijacked the other's navigation (#2674). Move them to shared partials with OEL and OSS shells; OEL is canonical per the self-hosted exception. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
unatasha8
left a comment
There was a problem hiding this comment.
Reviewing... please don't merge yet.
Migrates the kratos passwordless and MFA documentation to the deployment structure from
AGENTS.md, so Ory Network and OEL readers each keep their own sidebar navigation instead of sharing one doc that can only belong to a single sidebar.src/components/Shared/kratos/{passwordless,mfa}/(including their static assets).docs/network/kratos/...anddocs/oel/kratos/...import the partials; canonicals on both point to the Network URL per the default canonical rule.oel/kratos/mfa-overviewshell), fixing the missing OEL navigation context for feature docs.SameDeploymentLink; inbound links across the docs are updated accordingly.vercel.json: 14 new redirects for the old URLs plus 10 existing destinations retargeted to flatten redirect chains.docs/kratos/debug/*pages were autogenerated into both the OEL and OSS sidebars, so one deployment always hijacked the other's navigation. They now use the same shared-partial + shell structure for OEL and OSS with the self-hosted canonical exception (OEL self-canonical, OSS canonical → OEL, no Network shells), and the old URLs redirect to the OEL pages.Related Issue or Design Document
Part of #2674 (device authentication follows as a separate PR once #2673 lands).
Checklist
Further comments
Notes for reviewers:
docs/kratos/mfa/01_overview.mdx(its content lives on in the refreshed shared partial, with the "Device binding" → "Device authentication" rename pre-applied). docs: add device authentication with PIN and biometrics guide #2673 edits that file with the same rename, so it simply drops that hunk on rebase. Thedeviceauthnpage and both of its sidebar entries are deliberately untouched here — docs: add device authentication with PIN and biometrics guide #2673 owns them.vercel.jsondestinations use path-relative/docs/network/...form, matching the newest existing entries (older entries use absolutehttps://www.ory.com/...).oss=overrides in the MFA overview partial: six shells import it (network/oel/oss × top-level + quickstarts). Since this PR intentionally creates no OSS sub-page shells, the partial'sSameDeploymentLinks carryoss=overrides pointing OSS readers at the Network pages; without them the OSS pages would have broken links./docs/kratos/passwordless/*,/docs/kratos/mfa/*) 308-redirect to the new Network URLs; the custompasskeys-mobile-web-implementationslug is dropped in favor of the plainpasskeys-mobileslug (covered by a redirect).docusaurus buildpasses; the only remaining warnings are pre-existing (/docs/reference/openapi/*links and two stale/docs/reference/api#operation/...anchors that exist on master too).🤖 Generated with Claude Code
Summary by CodeRabbit