feat: add same deployment link util

.github/CODEOWNERS

@@ -1,4 +1,4 @@
-*                               @vinckr @aeneasr @zepatrik @piotrmsc @unatasha8
+*                               @vinckr @aeneasr @zepatrik @piotrmsc @unatasha8 @wassimoo
 *.md                            @vinckr @aeneasr @unatasha8
 *.mdx                           @vinckr @aeneasr @unatasha8
-/code-examples/                 @aeneasr @zepatrik @piotrmsc
+/code-examples/                 @aeneasr @zepatrik @piotrmsc @wassimoo

AGENTS.md

@@ -38,7 +38,7 @@ OR
 
 ### Shared Source Content
 
-- Location: `/src/components/shared/<product>/...`
+- Location: `/src/components/Shared/<product>/...`
 - Purpose:
   - Reusable, deployment-agnostic content
   - Written once, used across deployments
@@ -53,7 +53,7 @@ Locations:
 
 Shell files:
 
-- Import content from `/src/components/shared/...`
+- Import content from `/src/components/Shared/...`
 - Represent a page for a specific deployment
 - Are the files added to sidebars
 
@@ -101,12 +101,12 @@ If content is specific to **self-hosted (OEL/OSS)**: **OEL is canonical**
 
 ### 2. Update content
 
-- Edit shared source when possible:`/src/components/shared/<product>/...`
+- Edit shared source when possible: `/src/components/Shared/<product>/...`
 - Avoid duplicating content across deployments
 
 **Example (shared source):**
 
-`/src/components/shared/kratos/index.mdx`
+`/src/components/Shared/kratos/index.mdx`
 
 ```mdx
 Ory Kratos Identities is an API-first identity and user management system...
@@ -141,7 +141,7 @@ sidebar_label: Introduction
   <link rel="canonical" href="https://www.ory.com/docs/network/kratos/intro" />
 </head>
 
-import MyPartial from "@site/src/components/shared/kratos/index.mdx"
+import MyPartial from "@site/src/components/Shared/kratos/index.mdx"
 
 <MyPartial />
 ```
@@ -174,7 +174,7 @@ import MyPartial from "@site/src/components/shared/kratos/index.mdx"
 
 ### Summary
 
-- Edit → `/src/components/shared/...`
+- Edit → `/src/components/Shared/...`
 - Expose → `docs/<deployment>/...` shell files
 - Navigate → via sidebars
 - De-duplicate → with canonical URLs
@@ -190,5 +190,34 @@ import MyPartial from "@site/src/components/shared/kratos/index.mdx"
 ## When in Doubt
 
 - Check the sidebar first
-- Look for `/src/components/shared/...` usage
+- Look for `/src/components/Shared/...` usage
 - If unclear, ask the Docs team before making structural changes
+
+## MDX paths, imports, and internal links
+
+- **Use `@site` for imports (not links)**: use `@site/...` when importing
+  snippets/partials (for example `@site/src/components/Shared/...`) to avoid
+  brittle relative import paths. Do not use `@site` as a way to “link” to docs
+  pages.
+- **Don’t link to shared partials**: shared files in `src/components/Shared/...`
+  are implementation details; link to the deployment shell page(s) in
+  `docs/<deployment>/...` instead.
+- **Use `SameDeploymentLink` when linking across deployments**: if a doc exists
+  under `docs/network/...`, `docs/oel/...`, and `docs/oss/...`, use
+  `SameDeploymentLink` so readers stay on their current deployment. In this repo
+  it’s registered globally via `src/theme/MDXComponents.js`, so you can use it
+  in MDX without importing it.
+
+Example:
+
+```mdx
+<SameDeploymentLink to="kratos/intro">
+  Ory Kratos introduction
+</SameDeploymentLink>
+
+{/* Optional per-deployment overrides */}
+
+<SameDeploymentLink to="kratos/intro" oel="kratos/self-hosted/intro">
+  Kratos intro (deployment-aware)
+</SameDeploymentLink>
+```

src/components/SameDeploymentLink.tsx

@@ -0,0 +1,78 @@
+import React, { useEffect, type ReactNode } from "react"
+import Link from "@docusaurus/Link"
+import { useLocation } from "@docusaurus/router"
+import { useAllDocsData } from "@docusaurus/plugin-content-docs/client"
+
+type DocsDeploymentSegment = "network" | "oel" | "oss"
+
+type SameDeploymentLinkProps = {
+  to: string
+  // Optional overrides for the link target based on the deployment segment
+  network?: string
+  oel?: string
+  oss?: string
+  children: ReactNode
+}
+
+const DEFAULT_DOCS_PLUGIN_ID = "default"
+
+const DEPLOYMENT_SEGMENT_PATTERN = /\/(network|oel|oss)(?:\/|$)/
+
+const stripLeadingSlashes = (value: string) => value.replace(/^\/+/, "")
+const normalizePath = (value: string) => `/${stripLeadingSlashes(value)}`
+
+/**
+ * Internal docs link that keeps the reader on the current deployment (Network / OEL / OSS).
+ */
+export default function SameDeploymentLink({
+  to,
+  network,
+  oel,
+  oss,
+  children,
+}: SameDeploymentLinkProps): JSX.Element {
+  const { pathname } = useLocation()
+  const segment =
+    (pathname.match(DEPLOYMENT_SEGMENT_PATTERN)?.[1] as
+      | DocsDeploymentSegment
+      | undefined) ?? "network"
+
+  const rewriteToCurrentDeployment = (value: string): string => {
+    const path = normalizePath(value)
+    const match = path.match(DEPLOYMENT_SEGMENT_PATTERN)
+    if (match) {
+      // Replace explicit deployment segment with the current one.
+      return path.replace(DEPLOYMENT_SEGMENT_PATTERN, `/${segment}/`)
+    }
+    // Prefix when no deployment segment is present.
+    return `/${segment}${path}`
+  }
+
+  const overrideForCurrentDeployment = { network, oel, oss }[segment]
+  const href = overrideForCurrentDeployment
+    ? normalizePath(overrideForCurrentDeployment)
+    : rewriteToCurrentDeployment(to)
+  const allDocs = useAllDocsData()
+
+  useEffect(() => {
+    if (!DEPLOYMENT_SEGMENT_PATTERN.test(href)) return
+    const plugin = allDocs[DEFAULT_DOCS_PLUGIN_ID]
+    const version =
+      plugin?.versions.find((v) => v.isLast) ?? plugin?.versions[0]
+    if (!version?.docs?.length) return
+
+    const docId = stripLeadingSlashes(href)
+    const found = version.docs.some((d) => d.id === docId)
+    if (!found) {
+      const overrideMsg = overrideForCurrentDeployment
+        ? ` (override prop "${segment}" was used)`
+        : ""
+      console.warn(
+        `[SameDeploymentLink] No doc with id "${docId}". ` +
+          `Resolved href="${href}" from to="${to}" under deployment "${segment}" did not match any page in this build${overrideMsg}.`,
+      )
+    }
+  }, [allDocs, href, overrideForCurrentDeployment, segment, to])
+
+  return <Link to={href}>{children}</Link>
+}

src/components/Shared/kratos/index.mdx

@@ -24,8 +24,8 @@ modern software applications have to deal with:
 
 Ory Identities calls user accounts "identities". The terms "user accounts",
 "users", and "identities" are used interchangeably in the Ory documentation.
-Read [more here](../../../../docs/network/kratos/quickstarts/identity-model) to
-learn more about identities in Ory.
+Read <SameDeploymentLink to="kratos/quickstarts/identity-model">more
+here</SameDeploymentLink> to learn more about identities in Ory.
 
 :::
 

src/contexts/QuickstartsDeploymentContext.tsx

@@ -1,4 +1,10 @@
-import React, { createContext, useContext, useState, useCallback } from "react"
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useEffect,
+} from "react"
 
 export type QuickstartsDeploymentId = "network" | "oel" | "oss"
 
@@ -19,6 +25,13 @@ export function QuickstartsDeploymentProvider({
 }) {
   const [deployment, setDeploymentState] =
     useState<QuickstartsDeploymentId>(initialDeployment)
+
+  // Keep context in sync with explicitly segmented URLs (e.g. /docs/oel/...).
+  useEffect(() => {
+    if (initialDeployment === "network") return
+    setDeploymentState(initialDeployment)
+  }, [initialDeployment])
+
   const setDeployment = useCallback((id: QuickstartsDeploymentId) => {
     setDeploymentState(id)
   }, [])

src/theme/DocRoot/index.js

@@ -15,6 +15,7 @@ import {
   QuickstartsDeploymentProvider,
   useQuickstartsDeployment,
 } from "@site/src/contexts/QuickstartsDeploymentContext"
+import { docsDeploymentFromPathname } from "@site/src/utils/docsDeploymentFromPathname"
 
 const QUICKSTARTS_SIDEBAR = "quickstartsSidebar"
 
@@ -79,13 +80,14 @@ export default function DocRootWrapper(props) {
   }
   const { docElement, sidebarName, sidebarItems } = currentDocRouteMetadata
   const pathname = props.location?.pathname ?? ""
+  const deploymentFromPath = docsDeploymentFromPathname(pathname)
   const versionMetadata = useDocsVersion() ?? {}
   const docsSidebars = versionMetadata.docsSidebars ?? {}
 
   return (
     <div id="route-identifier" data-route={pathname}>
       <HtmlClassNameProvider className={clsx(ThemeClassNames.page.docsDocPage)}>
-        <QuickstartsDeploymentProvider>
+        <QuickstartsDeploymentProvider initialDeployment={deploymentFromPath}>
           <DocRootContent
             docElement={docElement}
             sidebarName={sidebarName}

src/theme/MDXComponents.js

@@ -4,12 +4,14 @@ import Tabs from "@theme/Tabs"
 import TabItem from "@theme/TabItem"
 import AjaxWarning from "./AjaxWarning"
 import ConsoleLink from "../components/ConsoleLink/console-link"
+import SameDeploymentLink from "../components/SameDeploymentLink"
 
 export default {
   // Re-use the default mapping
   ...MDXComponents,
   AjaxWarning,
   ConsoleLink,
+  SameDeploymentLink,
   Tabs,
   TabItem,
 }

src/utils/docsDeploymentFromPathname.ts

@@ -0,0 +1,27 @@
+export type DocsDeploymentId = "network" | "oel" | "oss"
+
+/**
+ * Infer the docs deployment from a pathname.
+ *
+ * Note: Some routes still use legacy `/docs/self-hosted/oel/...` paths.
+ */
+export function docsDeploymentFromPathname(pathname: string): DocsDeploymentId {
+  if (!pathname) return "network"
+
+  if (pathname.includes("/oel/") || pathname.includes("/self-hosted/oel/"))
+    return "oel"
+  if (pathname.includes("/oss/")) return "oss"
+  if (pathname.includes("/network/")) return "network"
+
+  return "network"
+}
+
+export function isExplicitDocsDeploymentPath(pathname: string): boolean {
+  if (!pathname) return false
+  return (
+    pathname.includes("/network/") ||
+    pathname.includes("/oel/") ||
+    pathname.includes("/oss/") ||
+    pathname.includes("/self-hosted/oel/")
+  )
+}