feat: new docs design by wassimoo · Pull Request #2505 · ory/docs

wassimoo · 2026-04-10T12:53:36Z

Preview link: https://docs-7qgoc8ot0-ory.vercel.app/docs/welcome

Summary

This PR delivers a significant redesign of the Ory documentation site, introducing a new Homepage navigation experience, a new Quick Start page, restructured content architecture, and visual design improvements. It also establishes the foundational framework for separating documentation by deployment model: Ory Network, Ory OEL, and Ory OSS.

Changes

Homepage navigation

Replaced the previous homepage with a guided navigation experience that helps technical evaluators and developers orient quickly and find the right entry point for their use case. (Aligns better with our marketing site.)

Quick Start page

Added a new Quick Start page as a dedicated onboarding path for developers getting started with Ory for the first time.

Content restructuring

Reorganized existing documentation to support clearer content hierarchy. This restructuring is a prerequisite for the deployment-model separation work.

Product overview

Added new high-level product explanations with visual elements to demonstrate how each product fits within the context of an IAM system.

Visual design enhancements

Updated layout, typography, and component styling throughout the portal for improved readability and consistency. Introduced product color association.

Deployment model framework

Introduced the structural scaffolding to separate documentation by deployment context — Ory Network, Ory OEL, and Ory OSS — enabling product-specific content targeting in follow-on PRs.

What's not included

Full content separation by deployment model is out of scope for this PR. This change puts the framework in place; content migration and product-specific pages will follow.
Complete alignment on product names is out of the scope of this PR.

TESTING

New feature documentation (last few months)

Verify your new content appears in the redesigned navigation (docs/sidebar.ts). If it doesn't appear, add it to the /docs/sidebar.ts.

NOTE: There are several new sidebar files located within the /docs folder; if your content was added to the previous sidebar.ts file located in /src that file is no longer in use.

Content is complete

Verify that your product area contains the expected full set of content. The restructure may have affected navigation visibility for some pages.

Broken links

Spot-check links in your product area. Internal navigation files were significantly changed in this redesign.

Checklist

[ X] I have read the contributing guidelines and signed the CLA.
I have referenced an issue containing the design document if my change introduces a new feature.
[X ] I have read the security policy.
[X ] I confirm that this pull request does not address a security vulnerability.
If this pull request addresses a security vulnerability,
I confirm that I got approval (please contact [email protected]) from the maintainers to push the changes.
I have added tests that prove my fix is effective or that my feature works.
I have added the necessary documentation within the code base (if appropriate).

jaygiang · 2026-04-10T16:25:56Z

docs/network/kratos/quickstarts/authenticate.mdx

+
+## [Password-based](/docs/kratos/concepts/credentials/username-email-password)
+
+Email/Username + Password: Traditional login using a password combined with an email address or username. [Configure password


The [Configure password login] seems to be incomplete, should there be a url target?

There's a couple below as well:

[Enable passkeys]

[One-time code auth]

[Social sign-in]

[Enterprise SSO]

[Login flows]

This file is not actually hooked up to the sidebar and is not being used. I will delete this file.

jaygiang · 2026-04-10T16:28:10Z

docs/network/kratos/quickstarts/intro.mdx

@@ -0,0 +1,12 @@
+---
+id: intro
+title: Introduction to Ory Kratos—Indentity & AuthN


"Indentity" typo

jaygiang · 2026-04-10T17:39:31Z

vercel.json

      "permanent": false
    },
    {
      "source": "/docs/hydra/benchmark",
-      "destination": "https://www.ory.com/docs/ecosystem/benchmark",
+      "destination": "https://www.ory.com/docs/docs/oauth2-oidc",


This destination takes user to a 404 page, I believe due to the double /docs/docs path

jaygiang · 2026-04-10T17:41:25Z

vercel.json

+      "permanent": true
+    },
+    {
+      "source": "/docs/open-source",


There's a duplicate of this in line 1301

jaygiang · 2026-04-10T17:43:10Z

vercel.json

+      "permanent": true
+    },
+    {
+      "source": "/docs/open-source/guidelines/rest-api-guidelines",


There is a duplicate of this on line 1306

jaygiang · 2026-04-10T17:43:55Z

vercel.json

+      "permanent": true
+    },
+    {
+      "source": "/docs/ecosystem/changelog",


There's a duplicate of this on line 1291

jaygiang · 2026-04-10T18:12:51Z

vercel.json

+      "permanent": true
+    },
+    {
+      "source": "/docs/guides/workspaces",


From line 1316-1354, it directs the user to 404 page. I believe these destination paths docs/network/ have no corresponding files. There are 8 of these

jaygiang · 2026-04-10T18:15:52Z

vercel.json

@@ -1220,17 +1220,262 @@
    {
      "source": "/docs/getting-started/integrate-auth/nextjs",
      "destination": "/docs/getting-started/integrate-auth/nextjs-app-router-quickstart",
-      "permanent": true
+      "permanent": false


This got changed to false, just checking if this was intentional. Same for line 1228

jaygiang · 2026-04-10T18:20:07Z

src/plugins/productLinePlugin.ts

@@ -0,0 +1,109 @@
+// Copyright © 2022 Ory Corp


This plugin doesn't seem to be used anywhere. Can we double check?

unatasha8 · 2026-04-10T19:30:31Z

docs/network/kratos/quickstarts/intro.mdx

@@ -0,0 +1,12 @@
+---
+id: intro
+title: Introduction to Ory Kratos—Indentity & AuthN


Suggested change

title: Introduction to Ory Kratos—Indentity & AuthN

title: Introduction to Ory Kratos—Identity & AuthN

unatasha8 · 2026-04-10T19:34:41Z

vercel.json

      "permanent": false
    },
    {
      "source": "/docs/hydra/benchmark",
-      "destination": "https://www.ory.com/docs/ecosystem/benchmark",
+      "destination": "https://www.ory.com/docs/docs/oauth2-oidc",


Suggested change

"destination": "https://www.ory.com/docs/docs/oauth2-oidc",

"destination": "https://www.ory.com/docs/oauth2-oidc",

unatasha8 · 2026-04-10T19:37:41Z

vercel.json

+      "destination": "/docs/oss/configuring",
+      "permanent": true
+    },
+    {


Suggested change

{

unatasha8 · 2026-04-10T19:37:56Z

vercel.json

+      "permanent": true
+    },
+    {
+      "source": "/docs/open-source",


Suggested change

"source": "/docs/open-source",

unatasha8 · 2026-04-10T19:38:05Z

vercel.json

+    },
+    {
+      "source": "/docs/open-source",
+      "destination": "/docs/oss/open-source",


Suggested change

"destination": "/docs/oss/open-source",

unatasha8 · 2026-04-10T19:38:14Z

vercel.json

+    {
+      "source": "/docs/open-source",
+      "destination": "/docs/oss/open-source",
+      "permanent": true


Suggested change

"permanent": true

unatasha8 · 2026-04-10T19:38:23Z

vercel.json

+      "source": "/docs/open-source",
+      "destination": "/docs/oss/open-source",
+      "permanent": true
+    },


Suggested change

},

vinckr · 2026-04-10T19:46:58Z

src/navbar.ts

    {
-      to: "/docs/ecosystem/projects",
-      label: "Open Source",
+      label: "Change Log",


Suggested change

label: "Change Log",

label: "Changelog",

Change Log looks odd to me, I think changelog is also the more common spelling (see e.g. wikipedia)

jaygiang · 2026-04-10T21:22:34Z

docusaurus.config.ts

  favicon: "img/favico.png",
-  onBrokenLinks: "throw",
-  onBrokenMarkdownLinks: "throw",
+  onBrokenLinks: "warn",


Should we change this back to throw? It helps us check for broken links when running build.

unatasha8 added 30 commits December 16, 2025 18:48

docs: update navbar

9352885

docs: add sidebar-agentic

cb0add9

docs: added sidebars-b2b

7b7584f

docs: added sidebars-ciam

642c9a6

docs: added sidebars-network

391f910

docs: added sidebars-oel

31f94e8

docs: add sidebars-oss

a0fe3dd

docs: add sidebars-quickstarts

7670bfe

add: sidebars.ts

623b993

docs: update config

8302acd

docs: add solution files

08f4826

docs: add agentic sol

661c668

docs: add b2g sol

5d0d369

docs: ciam sol

023e105

docs: add overview sol

0b09f84

docs: add ref overview

ae612d5

docs: add ref overview

4b058c6

docs: add prod overview

7ff1f4c

docs: add product eco

6ece2b6

docs: add product folders

4a3d246

docs: shared files

7abbc03

docs: add shared files

382f184

docs: modified

9910fa5

docs: modified

aaea48a

docs: modified

94336c7

docs: modified

1a653aa

docs: moved files

b40d809

docs: add quickstart

ddc47ce

docs: add filters

7795bb7

docs: add constants

58e6bd6

wassimoo changed the title ~~Una redesign imp2~~ New docs design Apr 10, 2026

github-actions bot added the Needs Triage label Apr 10, 2026

ory-bot assigned wassimoo Apr 10, 2026

wassimoo changed the title ~~New docs design~~ feat: new docs design Apr 10, 2026

vercel bot deployed to Preview April 10, 2026 12:59 View deployment

fix: formatting for MCP server link in ContentSection

414f300

vercel bot deployed to Preview April 10, 2026 13:08 View deployment

wassimoo marked this pull request as ready for review April 10, 2026 15:11

wassimoo requested review from aeneasr, piotrmsc, unatasha8, vinckr and zepatrik as code owners April 10, 2026 15:11

wassimoo requested review from adamwalach, alnr, hperl, jaygiang, jonas-jonas, mszekiel and ricardo-osorio-santos April 10, 2026 15:13

jaygiang requested changes Apr 10, 2026

View reviewed changes

unatasha8 reviewed Apr 10, 2026

View reviewed changes

vercel.json

"destination": "/docs/oss/configuring",

"permanent": true

},

{

Copy link
Copy Markdown

Contributor

unatasha8 Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

{

unatasha8 reviewed Apr 10, 2026

View reviewed changes

vinckr reviewed Apr 10, 2026

View reviewed changes

jaygiang reviewed Apr 10, 2026

View reviewed changes


		## [Password-based](/docs/kratos/concepts/credentials/username-email-password)

		Email/Username + Password: Traditional login using a password combined with an email address or username. [Configure password

	title: Introduction to Ory Kratos—Indentity & AuthN
	title: Introduction to Ory Kratos—Identity & AuthN

	"destination": "https://www.ory.com/docs/docs/oauth2-oidc",
	"destination": "https://www.ory.com/docs/oauth2-oidc",

Conversation

wassimoo commented Apr 10, 2026 • edited by unatasha8 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

What's not included

TESTING

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaygiang Apr 10, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

17 participants

wassimoo commented Apr 10, 2026 •

edited by unatasha8

Loading

jaygiang Apr 10, 2026 •

edited

Loading