new docs site updates (#6157)

.gitignore

@@ -29,3 +29,6 @@
 # Previous git submodules
 dockerfiles/federation-demo
 dockerfiles/federation2-demo
+
+# macOS
+.DS_Store

docs/shared/native-plugin-notice.mdx

@@ -3,6 +3,6 @@
 - Native plugins require familiarity with programming in Rust.
 - Native plugins require compiling a custom router binary from source, which can introduce unexpected behavior in your router that's difficult to diagnose and support.
 
-Instead, for most router customizations, Apollo recommends creating either a [Rhai script](https://www.apollographql.com/docs/router/customizations/rhai/) or an [external coprocessor](https://www.apollographql.com/docs/router/customizations/coprocessor). Both of these customizations are supported by Apollo and provide strong separation of concerns and fault isolation.
+Instead, for most router customizations, Apollo recommends creating either a [Rhai script](https://www.apollographql.com/docs/graphos/routing/customization/rhai/) or an [external coprocessor](https://www.apollographql.com/docs/router/customizations/coprocessor). Both of these customizations are supported by Apollo and provide strong separation of concerns and fault isolation.
 
 If you must create a native plugin, please [open a GitHub issue](https://github.com/apollographql/router/issues), and Apollo can investigate adding the custom capability to the stock router binary.

docs/source/config.json

@@ -2,130 +2,16 @@
   "title": "Self-Hosted Router",
   "algoliaFilters": ["docset:router"],
   "sidebar": {
-    "Introduction": "/",
-    "Quickstart": "/quickstart",
-    "Moving from @apollo/gateway": "/migrating-from-gateway",
-    "Federation Version Support": "/federation-version-support",
-    "Enterprise Features": ["/enterprise-features", ["enterprise"]],
-    "Configuring the Router": {
-      "Overview": "/configuration/overview",
-      "Caching": {
-        "In-Memory Caching": "/configuration/in-memory-caching",
-        "Distributed Caching": ["/configuration/distributed-caching", ["enterprise"]],
-        "Entity Caching": ["/configuration/entity-caching", ["enterprise", "preview"]]
-      },
-      "Debugging": {
-        "Errors": "/errors",
-        "Telemetry": "/configuration/telemetry/overview",
-        "Subgraph Error Inclusion": "/configuration/subgraph-error-inclusion"
-      },
-      "Networking": {
-        "Header Propagation": "/configuration/header-propagation",
-        "Traffic Shaping": "/configuration/traffic-shaping"
-      },
-      "Security": {
-        "CORS": "/configuration/cors",
-        "CSRF Prevention": "/configuration/csrf",
-        "JWT Authentication": ["/configuration/authn-jwt", ["enterprise"]],
-        "Authorization": ["/configuration/authorization", ["enterprise"]],
-        "Subgraph Authentication": "/configuration/authn-subgraph",
-        "Operation Limits": [
-          "/configuration/operation-limits",
-          [
-            "enterprise"
-          ]
-        ],
-        "Safelisting with Persisted Queries": [
-          "/configuration/persisted-queries",
-          [
-            "enterprise"
-          ]
-        ],
-        "Demand Control" : [
-          "/executing-operations/demand-control",
-          [
-            "enterprise"
-          ]
-        ],
-        "Privacy and Data Collection": "/privacy"
-      }
-    },
-    "Executing Operations": {
-      "Build and Run Queries": "/executing-operations/build-run-queries",
-      "@defer Support": "/executing-operations/defer-support",
-      "Request Format": "/executing-operations/requests",
-      "Query Batching": [
-        "/executing-operations/query-batching",
-        [
-          "enterprise"
-        ]
-      ],
-      "GraphQL Subscriptions": {
-        "Subscriptions Setup": ["/executing-operations/subscription-support", ["enterprise"]],
-        "Subgraph Protocol: HTTP Callback": [
-          "/executing-operations/subscription-callback-protocol",
-          ["enterprise", "preview"]
-        ],
-        "Client Protocol: HTTP Multipart": ["/executing-operations/subscription-multipart-protocol", ["enterprise"]]
-      }
+    "Routing": {
+      "About Router": "/routing/about-router"
     },
-    "Telemetry and Monitoring": {
-      "Overview": "/configuration/telemetry/overview",
-      "GraphOS Reporting": "/configuration/telemetry/apollo-telemetry",
-      "Client Awareness": "/managed-federation/client-awareness",
-      "Log Exporters": {
-        "Configuration": "/configuration/telemetry/exporters/logging/overview",
-        "Stdout": "/configuration/telemetry/exporters/logging/stdout"
+    "Reference": {
+      "Migration": {
+        "From Gateway": "/reference/migration/from-gateway"
       },
-      "Metrics Exporters": {
-        "Configuration": "/configuration/telemetry/exporters/metrics/overview",
-        "Datadog": "/configuration/telemetry/exporters/metrics/datadog",
-        "Dynatrace": "/configuration/telemetry/exporters/metrics/dynatrace",
-        "New Relic": "/configuration/telemetry/exporters/metrics/new-relic",
-        "OTLP": "/configuration/telemetry/exporters/metrics/otlp",
-        "Prometheus": "/configuration/telemetry/exporters/metrics/prometheus"
-      },
-      "Trace exporters": {
-        "Configuration": "/configuration/telemetry/exporters/tracing/overview",
-        "Datadog": "/configuration/telemetry/exporters/tracing/datadog",
-        "Dynatrace": "/configuration/telemetry/exporters/tracing/dynatrace",
-        "Jaeger": "/configuration/telemetry/exporters/tracing/jaeger",
-        "New Relic": "/configuration/telemetry/exporters/tracing/new-relic",
-        "OTLP": "/configuration/telemetry/exporters/tracing/otlp",
-        "Zipkin": "/configuration/telemetry/exporters/tracing/zipkin"
-      },
-      "Instrumentation": {
-        "Instruments": "/configuration/telemetry/instrumentation/instruments",
-        "Events": "/configuration/telemetry/instrumentation/events",
-        "Conditions": "/configuration/telemetry/instrumentation/conditions",
-        "Spans": "/configuration/telemetry/instrumentation/spans",
-        "Selectors": "/configuration/telemetry/instrumentation/selectors",
-        "Standard Attributes": "/configuration/telemetry/instrumentation/standard-attributes",
-        "Standard Instruments": "/configuration/telemetry/instrumentation/standard-instruments"
+      "Router": {
+        "Configuration": "/reference/router/configuration"
       }
-    },
-    "Containerization": {
-      "Overview": "/containerization/overview",
-      "Deploy on Kubernetes": "/containerization/kubernetes",
-      "Run with Docker": "/containerization/docker",
-      "Health Checks": "/configuration/health-checks"
-    },
-    "Managed Federation": {
-      "Overview": "https://www.apollographql.com/docs/federation/managed-federation/overview",
-      "Setup": "https://www.apollographql.com/docs/federation/managed-federation/setup",
-      "GraphOS Studio Features": "https://www.apollographql.com/docs/graphos/graphs/federated-graphs"
-    },
-    "Customizations": {
-      "Overview": "/customizations/overview",
-      "Rhai Scripts": "/customizations/rhai",
-      "Rhai API Reference": "/customizations/rhai-api",
-      "External Coprocessing": ["/customizations/coprocessor", ["enterprise"]],
-      "Native Rust Plugins": "/customizations/native",
-      "Custom Router Binary": "/customizations/custom-binary"
-    },
-    "Subgraph Support": {
-      "Subgraph-Compatible Libraries": "https://www.apollographql.com/docs/federation/v2/other-servers/",
-      "Subgraph Specification": "https://www.apollographql.com/docs/federation/v2/federation-spec/"
     }
   }
 }

docs/source/enterprise-features.mdx

@@ -31,10 +31,10 @@ For details on these features, see [this blog post](https://blog.apollographql.c
 To enable support for GraphOS Router Enterprise features:
 
 - Your organization must have a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/).
-- You must run GraphOS Router v1.12. [Download the latest version.](./quickstart#download-options)
+- You must run GraphOS Router v1.12. [Download the latest version.](/router/quickstart#download-options)
     - Certain Enterprise features might require a later router version. See a particular feature's documentation for details.
 - Your router instances must connect to GraphOS with a **graph API key** and **graph ref** associated with your organization.
-    - You connect your router to GraphOS by setting [these environment variables](./configuration/overview/#environment-variables) when starting the router.
+    - You connect your router to GraphOS by setting [these environment variables](/router/configuration/overview/#environment-variables) when starting the router.
     - If your router _already_ connects to your GraphOS Enterprise organization, no further action is required.
 
 After enabling support, you can begin using all Enterprise features. Consult [the documentation for each feature](#list-of-features) to learn more.
@@ -82,7 +82,7 @@ With an offline license, a router can either be fully disconnected from GraphOS
 
 <Note>
 
-A router using an offline license requires [the use of local manifests](./configuration/persisted-queries/#experimental_local_manifests) when using [safelisting with persisted queries](./configuration/persisted-queries), otherwise it will not work as designed when the router is disconnected from Uplink.
+A router using an offline license requires [the use of local manifests](/router/configuration/persisted-queries/#experimental_local_manifests) when using [safelisting with persisted queries](/router/configuration/persisted-queries), otherwise it will not work as designed when the router is disconnected from Uplink.
 
 </Note>
 
@@ -100,9 +100,9 @@ Follow these steps to configure an GraphOS Router to use an offline Enterprise l
 
 1. Provide the offline license to your router on startup. The router accepts an offline license in a few ways:
 
-    1. [`--license <license_path>`](./configuration/overview/#--license) CLI option, with an argument containing an absolute or relative path to an offline license file
-    1. [`APOLLO_ROUTER_LICENSE_PATH`](./configuration/overview/#--license) environment variable, containing an absolute or relative path to an offline license file 
-    1. [`APOLLO_ROUTER_LICENSE`](./configuration/overview/#--license) environment variable, containing the stringified contents of an offline license file
+    1. [`--license <license_path>`](/router/configuration/overview/#--license) CLI option, with an argument containing an absolute or relative path to an offline license file
+    1. [`APOLLO_ROUTER_LICENSE_PATH`](/router/configuration/overview/#--license) environment variable, containing an absolute or relative path to an offline license file 
+    1. [`APOLLO_ROUTER_LICENSE`](/router/configuration/overview/#--license) environment variable, containing the stringified contents of an offline license file
 
     <Note>
 
@@ -113,11 +113,11 @@ Follow these steps to configure an GraphOS Router to use an offline Enterprise l
 
 1. Configure the router to use a local supergraph schema by setting one of the following:
 
-    * [`--s/-supergraph`](./configuration/overview/#-s----supergraph) CLI option, with an argument containing an absolute or relative path to supergraph schema file
-    * [`APOLLO_SUPERGRAPH_PATH`](./configuration/overview/#-s----supergraph) environment variable, containing an absolute or relative path to supergraph schema file
-    * [`APOLLO_SUPERGRAPH_URLS`](./configuration/overview/#-s----supergraph) environment variable, containing URLs to supergraph schemas
+    * [`--s/-supergraph`](/router/configuration/overview/#-s----supergraph) CLI option, with an argument containing an absolute or relative path to supergraph schema file
+    * [`APOLLO_SUPERGRAPH_PATH`](/router/configuration/overview/#-s----supergraph) environment variable, containing an absolute or relative path to supergraph schema file
+    * [`APOLLO_SUPERGRAPH_URLS`](/router/configuration/overview/#-s----supergraph) environment variable, containing URLs to supergraph schemas
 
-1. (**Recommended**) Configure the router to report usage metrics to GraphOS in a best-effort basis by setting both the [`APOLLO_KEY`](./configuration/overview/#apollo_key) and [`APOLLO_GRAPH_REF`](./configuration/overview#apollo_graph_ref) environment variables. 
+1. (**Recommended**) Configure the router to report usage metrics to GraphOS in a best-effort basis by setting both the [`APOLLO_KEY`](/router/configuration/overview/#apollo_key) and [`APOLLO_GRAPH_REF`](/router/configuration/overview#apollo_graph_ref) environment variables. 
 
     These metrics are necessary for several important GraphOS features (operations checks, field insights, operation traces, contracts). Sending them best-effort incurs no performance or uptime penalties. 
 
@@ -168,7 +168,7 @@ These steps work both for running the router executable directly (`./router`) an
 
 ## Disabling Enterprise features
 
-To disable an Enterprise feature, remove all of its associated configuration keys from your router's [YAML config file](./configuration/overview/#yaml-config-file).
+To disable an Enterprise feature, remove all of its associated configuration keys from your router's [YAML config file](/router/configuration/overview/#yaml-config-file).
 
 ## Grace period for expired plans