Skip to content

AGENTS.md

Latest commit

 

History

History
223 lines (150 loc) · 5.23 KB

AGENTS.md

File metadata and controls

223 lines (150 loc) · 5.23 KB

Updating Ory Documentation

Overview

Ory documentation is being organized by deployment model:

  • Ory Network → docs/network
  • Ory Enterprise License (OEL) → docs/oel
  • Ory Open Source (OSS) → docs/oss

Current State (Transitional Phase)

  • Most content is still co-mingled
  • Only some sections (e.g. Quickstarts) use the new structure
  • The Docs team is actively splitting content

What you should do

  • Non-migrated sections → continue using the existing structure
  • Migrated sections → follow the new pattern
  • Do not restructure content yourself unless it has already been migrated

How to Tell if Content is Migrated

A section is migrated if:

  • The sidebar shows routes like:
    • docs/network/...
    • docs/oel/...
    • docs/oss/...

OR

  • You cannot find the page in the old structure and it exists under one of the deployment folders above

New Structure (Migrated Sections Only)

Shared Source Content

  • Location: /src/components/Shared/<product>/...
  • Purpose:
    • Reusable, deployment-agnostic content
    • Written once, used across deployments

Deployment Shell Files

Locations:

  • docs/network
  • docs/oel
  • docs/oss

Shell files:

  • Import content from /src/components/Shared/...
  • Represent a page for a specific deployment
  • Are the files added to sidebars

Sidebars

  • Each deployment has its own sidebar

When adding a page:

  • Add the shell file (not the shared source file)
  • Only include it in deployments where the feature exists

Canonical URL Rules (SEO)

When the same content exists across multiple deployments, you must define a canonical URL.

Default (Most Cases)

Ory Network is canonical

  • Network → self-canonical
  • OEL → canonical points to Network
  • OSS → canonical points to Network

Self-Hosted Exception

If content is specific to self-hosted (OEL/OSS): OEL is canonical

  • OEL → self-canonical
  • OSS → canonical points to OEL
  • Network → usually not applicable

How to Update Content (Migrated Sections)

1. Determine deployment availability

  • Is this available in:
    • Network
    • OEL
    • OSS
  • Be explicit, even if it’s only available in one for now

2. Update content

  • Edit shared source when possible: /src/components/Shared/<product>/...
  • Avoid duplicating content across deployments

Example (shared source):

/src/components/Shared/kratos/index.mdx

Ory Kratos Identities is an API-first identity and user management system...

- Self-service login and registration
- Multi-factor authentication
- Account recovery

3. Wire it into deployments

  • Ensure a shell file exists in each relevant deployment:
    • docs/network/...
    • docs/oel/...
    • docs/oss/...
  • Import the shared content into the shell file

Example (Network shell):

/docs/network/kratos/intro.mdx

---
id: intro
title: Introduction to Ory Kratos for Ory Network
sidebar_label: Introduction
---

<head>
  <link rel="canonical" href="https://www.ory.com/docs/network/kratos/intro" />
</head>

import MyPartial from "@site/src/components/Shared/kratos/index.mdx"

<MyPartial />

4. Update sidebar

  • Add the shell file (not the shared file) to the correct sidebar
  • Only include it in deployments where the feature exists

5. Set canonical URLs

  • Follow canonical rules:

Default:

  • Network → self-canonical
  • OEL / OSS → point to Network

Self-hosted exception:

  • OEL → self-canonical
  • OSS → point to OEL
  • Canonical is defined in the shell file:
<link rel="canonical" href="..." />

Summary

  • Edit → /src/components/Shared/...
  • Expose → docs/<deployment>/... shell files
  • Navigate → via sidebars
  • De-duplicate → with canonical URLs

Rule of Thumb

  • Old section → leave as-is
  • Migrated section → use shared content + shell files
  • Can’t find a page → check docs/network, docs/oel, docs/oss
  • Duplicate content → always set canonical URLs
  • Adding a page → update the correct sidebar

When in Doubt

  • Check the sidebar first
  • 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:

<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>