docs: update frontmatter (#2992)

Updates subtitles and meta descriptions for better discoverability.
apollographql · May 30, 2024 · 19746ad · 19746ad
1 parent 10737e2
commit 19746ad
Show file tree

Hide file tree

Showing 36 changed files with 122 additions and 79 deletions.
diff --git a/docs/source/building-supergraphs/jetbrains-ide-support.mdx b/docs/source/building-supergraphs/jetbrains-ide-support.mdx
@@ -1,5 +1,7 @@
 ---
-title: Federation support in JetBrains IDEs
+title: Federation Support in JetBrains IDEs
+subtitle: Streamline federated GraphQL development
+description: Enhance your development workflow with federation-specific features in IntelliJ-based IDEs using the GraphQL Plugin. 
 ---
 
 The [GraphQL Plugin for JetBrains](https://plugins.jetbrains.com/plugin/8097-graphql/) provides federation-specific development features, such as auto-complete for federation directives. However, you must enable this federation support after installing the plugin. Otherwise, your IDE might display unexpected errors while you're working with a subgraph schema.

diff --git a/docs/source/building-supergraphs/router.mdx b/docs/source/building-supergraphs/router.mdx
@@ -1,6 +1,7 @@
 ---
-title: The router
-description: The entry point to your supergraph
+title: The Router
+subtitle: Learn about the entry point to your federated GraphQL API
+description: Learn how to configure a router to act as the gateway to your subgraphs, facilitating seamless execution of operations across multiple services. Efficiently manage and orchestrate your federated supergraph with a robust router setup.
 ---
 
 After you set up at least one federation-ready [subgraph](./subgraphs-overview/), you can configure a router to sit in front of your subgraphs. The router serves as the entry point to your supergraph, and it executes incoming operations across one or more of your subgraphs:
@@ -25,7 +26,7 @@ Apollo actively supports the following options for your router:
 - **The Apollo Router (recommended)**: This is a high-performance, precompiled Rust binary.
 
     - If you're getting started with federation, we recommend [creating a cloud supergraph](/graphos/quickstart/cloud/) with Apollo GraphOS. With a cloud supergraph, GraphOS provisions and manages your router for you.
-    - You can also host your own Apollo Router instances. [See the federation quickstart](../quickstart/setup/) to get started.
+    - You can also host your own Apollo Router instances. [See the Federation Quickstart](../quickstart/setup/) to get started.
 
 - **Apollo Server**: Apollo Server can act as your router via the [`@apollo/gateway`](https://www.npmjs.com/package/@apollo/gateway) extension library.
     - [See how to set up Apollo Gateway](/apollo-server/using-federation/apollo-gateway-setup).

diff --git a/docs/source/building-supergraphs/subgraphs-overview.mdx b/docs/source/building-supergraphs/subgraphs-overview.mdx
@@ -1,6 +1,7 @@
 ---
 title: Subgraphs
-description: In a federated supergraph
+subtitle: Learn about subgraphs in a federated supergraph
+description: Understand the concept of subgraphs, explore library options, and learn how to secure and optimize your subgraphs for efficient supergraph operations. 
 ---
 
 Every federated supergraph includes one or more _subgraphs_. Each subgraph is a separate GraphQL service that's responsible for a different portion of your supergraph's available data.
@@ -20,7 +21,7 @@ flowchart LR;
   class clients secondary;
 ```
 
-You can implement different subgraphs using completely different programming languages and GraphQL server libraries!
+You can implement different subgraphs using completely different programming languages and GraphQL server libraries.
 
 ## Choosing a subgraph library
 

diff --git a/docs/source/building-supergraphs/supported-subgraphs.md b/docs/source/building-supergraphs/supported-subgraphs.md
@@ -1,6 +1,7 @@
 ---
-title: Federation-compatible subgraph implementations
-description: For use in a federated supergraph
+title: Federation-Compatible Subgraph Implementations
+subtitle: Reference for compatible GraphQL server libraries
+description: Reference for open-source GraphQL server libraries and hosted solutions that are compatible with Apollo Federation.
 ---
 
 The following open-source GraphQL server libraries and hosted solutions support acting as a subgraph in a federated supergraph. Their support is tracked in Apollo's [subgraph compatibility repository](https://github.com/apollographql/apollo-federation-subgraph-compatibility). Check out the repository for details on the compatibility tests listed in the table below.

diff --git a/docs/source/config.json b/docs/source/config.json
@@ -14,57 +14,57 @@
     "Introduction": "/",
     "Changelog": "/federation-versions",
     "Quickstart": {
-      "Project setup": "/quickstart/setup",
+      "Project Setup": "/quickstart/setup",
       "Composition in GraphOS Studio": "/quickstart/studio-composition",
-      "Local composition": "/quickstart/local-composition",
-      "Working with subgraphs": "/quickstart/local-subgraphs"
+      "Local Composition": "/quickstart/local-composition",
+      "Working with Subgraphs": "/quickstart/local-subgraphs"
     },
     "Building Your Supergraph": {
       "Subgraphs": "/building-supergraphs/subgraphs-overview",
-      "Supported subgraph libraries": "/building-supergraphs/supported-subgraphs",
-      "Router / Gateway": "/building-supergraphs/router",
-      "Apollo Server subgraphs": "https://apollographql.com/docs/apollo-server/using-federation/apollo-subgraph-setup",
+      "Supported Subgraph Libraries": "/building-supergraphs/supported-subgraphs",
+      "Router": "/building-supergraphs/router",
+      "Apollo Server Subgraphs": "https://apollographql.com/docs/apollo-server/using-federation/apollo-subgraph-setup",
       "JetBrains IDE Support": "/building-supergraphs/jetbrains-ide-support"
     },
     "Federated Schemas": {
       "Overview": "/federated-types/overview",
       "Composition": "/federated-types/composition",
-      "Federated directives": "/federated-types/federated-directives",
-      "Sharing types (value types)": "/federated-types/sharing-types",
-      "Introduction to entities": "/entities",
-      "Advanced entities": "/entities-advanced",
-      "Entity interfaces": "/federated-types/interfaces",
-      "Migrating from schema stitching": "/migrating-from-stitching"
+      "Federated Directives": "/federated-types/federated-directives",
+      "Sharing Types (Value Types)": "/federated-types/sharing-types",
+      "Introduction to Entities": "/entities",
+      "Advanced Entities": "/entities-advanced",
+      "Entity Interfaces": "/federated-types/interfaces",
+      "Migrating from Schema Stitching": "/migrating-from-stitching"
     },
     "Managed Federation": {
       "Overview": "/managed-federation/overview",
       "Setup": "/managed-federation/setup",
       "Uplink": "/managed-federation/uplink",
-      "Federated schema checks": "/managed-federation/federated-schema-checks",
-      "Deployment best practices": "/managed-federation/deployment",
-      "Opt-in error reporting": "/managed-federation/error-reporting",
-      "Studio features": "https://www.apollographql.com/docs/graphos/graphs/federated-graphs"
+      "Federated Schema Checks": "/managed-federation/federated-schema-checks",
+      "Deployment Best Practices": "/managed-federation/deployment",
+      "Opt-In Error Reporting": "/managed-federation/error-reporting",
+      "Studio Features": "https://www.apollographql.com/docs/graphos/graphs/federated-graphs"
     },
     "Performance": {
       "Caching": "/performance/caching",
       "Monitoring": "/performance/monitoring",
-      "Query plans": "/query-plans"
+      "Query Plans": "/query-plans"
     },
     "Debugging & Metrics": {
-      "Error codes": "/errors",
-      "Composition hints": "/hints",
-      "Federated trace data": "/metrics",
+      "Error Codes": "/errors",
+      "Composition Hints": "/hints",
+      "Federated Trace Data": "/metrics",
       "OpenTelemetry": "/opentelemetry"
     },
     "API Reference": {
-      "Subgraph specification": "/subgraph-spec",
+      "Subgraph Specification": "/subgraph-spec",
       "@apollo/subgraph": "https://apollographql.com/docs/apollo-server/using-federation/api/apollo-subgraph",
       "@apollo/gateway": "https://apollographql.com/docs/apollo-server/using-federation/api/apollo-gateway"
     },
     "Moving from Federation 1": {
       "Changes from Federation 1": "/federation-2/new-in-federation-2",
-      "Steps to move": "/federation-2/moving-to-federation-2",
-      "Backward compatibility": "/federation-2/backward-compatibility"
+      "Steps to Move": "/federation-2/moving-to-federation-2",
+      "Backward Compatibility": "/federation-2/backward-compatibility"
     }
   }
 }
diff --git a/docs/source/entities-advanced.mdx b/docs/source/entities-advanced.mdx
@@ -1,5 +1,7 @@
 ---
-title: Advanced topics on federated entities
+title: Advanced Topics on Federated Entities
+subtitle: Learn about advanced use cases for entities
+description: Explore advanced use cases for entities in a federated GraphQL architecture, including compound keys, migrating entity fields, and contributing computed fields.
 ---
 
 import ProgressiveOverrideEnterprise from '../shared/progressive-override-enterprise.mdx';

diff --git a/docs/source/entities.mdx b/docs/source/entities.mdx
@@ -1,6 +1,7 @@
 ---
 title: Entities in Apollo Federation
-description: Resolve types across multiple subgraphs
+subtitle: Learn how to resolve federated types across multiple subgraphs
+description: Learn to define, contribute to, and reference object types that resolve their fields across multiple subgraphs in a federated GraphQL architecture.
 ---
 
 <Note>

diff --git a/docs/source/errors.mdx b/docs/source/errors.mdx
@@ -1,6 +1,7 @@
 ---
-title: Federation error codes
-description: Learn the error codes you can receive if composition fails.
+title: Apollo Federation Error Codes
+subtitle: Reference for composition error codes
+description: Reference the error codes encountered during Apollo Federation schema composition, identifying root causes and solutions for GraphQL debugging.
 toc: false
 ---
 

diff --git a/docs/source/federated-types/composition.mdx b/docs/source/federated-types/composition.mdx
@@ -1,6 +1,7 @@
 ---
-title: Schema composition
-description: In Apollo Federation
+title: Schema Composition
+subtitle: Learn how subgraph schemas combine into a supergraph schema
+description: Learn about schema composition in a federated GraphQL architecture. Explore strategies for handling conflicting types and directives.
 ---
 
 In Apollo Federation, _composition_ is the process of combining a set of [subgraph schemas](./overview/#subgraph-schemas) into a [supergraph schema](./overview/#supergraph-schema):

diff --git a/docs/source/federated-types/federated-directives.mdx b/docs/source/federated-types/federated-directives.mdx
@@ -1,5 +1,7 @@
 ---
-title: Federation-specific GraphQL directives
+title: Apollo Federation Directives
+subtitle: Reference for Apollo Federation specific GraphQL directives
+description: Reference for GraphQL federation directives including @key, @extends, @sharable, @override, @requires and more.
 ---
 
 import ProgressiveOverrideEnterprise from '../../shared/progressive-override-enterprise.mdx';

diff --git a/docs/source/federated-types/interfaces.mdx b/docs/source/federated-types/interfaces.mdx
@@ -1,6 +1,7 @@
 ---
-title: Entity interfaces
-description: Add entity fields polymorphically
+title: Entity Interfaces
+subtitle: Add entity fields polymorphically
+description: Discover how to efficiently add polymorphic fields to GraphQL interfaces using Apollo Federation's Entity Interfaces and the @interfaceObject directive.
 minVersion: 2.3
 ---
 

diff --git a/docs/source/federated-types/overview.mdx b/docs/source/federated-types/overview.mdx
@@ -1,6 +1,7 @@
 ---
-title: Federated schemas
-description: Overview
+title: Federated Schemas
+subtitle: Learn about the different types of GraphQL schemas
+description: Learn about subgraph, supergraph, and API schemas in federated GraphQL architectures.
 ---
 
 A federated supergraph uses multiple "types" of GraphQL schemas:

diff --git a/docs/source/federated-types/sharing-types.mdx b/docs/source/federated-types/sharing-types.mdx
@@ -1,6 +1,7 @@
 ---
-title: Value types in Apollo Federation
-description: Share types and fields across multiple subgraphs
+title: Value Types in Apollo Federation
+subtitle: Share types and fields across multiple subgraphs
+description: Learn how to share GraphQL types and fields across subgraphs with Apollo Federation.
 ---
 
 In a federated graph, it's common to want to reuse a GraphQL type across multiple [subgraphs](../building-supergraphs/subgraphs-overview/).

diff --git a/docs/source/federation-2/backward-compatibility.mdx b/docs/source/federation-2/backward-compatibility.mdx
@@ -1,6 +1,7 @@
 ---
-title: Backward compatibility in Federation 2
-description: FAQ
+title: Backward Compatibility in Apollo Federation 2
+subtitle: Navigating the transition from Apollo Federation 1 to Federation 2
+description: Frequently asked questions when transitioning from Apollo Federation 1 to Federation 2.
 ---
 
 ## Is official support ending for `@apollo/gateway` v0.x?

diff --git a/docs/source/federation-2/moving-to-federation-2.mdx b/docs/source/federation-2/moving-to-federation-2.mdx
@@ -1,6 +1,7 @@
 ---
 title: Moving to Apollo Federation 2
-description: Upgrade your supergraph incrementally at any pace
+subtitle: Upgrade from Apollo Federation 1 to Federation 2
+description: Upgrade from Apollo Federation 1 to Federation 2 to benefit from improved composition logic and schema flexibility. 
 ---
 
 > 📣 If you haven't yet, [see what's new in Federation 2.](./new-in-federation-2/)

diff --git a/docs/source/federation-2/new-in-federation-2.mdx b/docs/source/federation-2/new-in-federation-2.mdx
@@ -1,5 +1,7 @@
 ---
-title: Changes from Federation 1 to Federation 2
+title: Changes from Apollo Federation 1
+subtitle: Learn what's new in Apollo Federation 2
+description: Explore the improvements and changes from Apollo Federation 1 to Federation 2, enhancing flexibility and schema composition in GraphQL.
 ---
 
 Apollo Federation 2 provides developer experience improvements to the original specification for Apollo Federation (called _Federation 1_ in these docs). If your organization has an existing Federation 1 graph, this article summarizes the benefits of [moving to Federation 2](./moving-to-federation-2/).

diff --git a/docs/source/federation-versions.mdx b/docs/source/federation-versions.mdx
@@ -1,6 +1,7 @@
 ---
-title: Federation version changelog
-description: Understand changes between federation versions
+title: Apollo Federation Changelog
+subtitle: Understand changes between Apollo Federation versions
+description: Understand changes between Apollo Federation major and minor versions.
 ---
 
 This article describes notable changes and additions introduced in each minor version release of Apollo Federation. Most of these changes involve additions or modifications to [federation-specific directives](./federated-types/federated-directives/).

diff --git a/docs/source/hints.mdx b/docs/source/hints.mdx
@@ -1,5 +1,7 @@
 ---
-title: Composition hints
+title: Composition Hints
+subtitle: Reference for composition hints
+description: Learn about hints flagged during Apollo Federation schema composition using GraphOS Studio or the Rover CLI.
 ---
 
 When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process can flag potential improvements or hints. Hints are violations of the [GraphOS schema linter's](/graphos/delivery/schema-linter) [composition rules](/graphos/delivery/linter-rules#composition-rules). You can review them on the [Checks](/graphos/delivery/schema-checks) page in GraphOS Studio or via the [Rover CLI](/rover/).

diff --git a/docs/source/index.mdx b/docs/source/index.mdx
@@ -1,7 +1,7 @@
 ---
 title: Introduction to Apollo Federation
 subtitle: Learn how to combine your GraphQL APIs into a unified supergraph
-description: Learn how Apollo Federation can help you declaratively combine your GraphQL APIs into a unified, federated supergraph using a microservices architecture
+description: Learn how Apollo Federation can help you declaratively combine your services into a unified, federated GraphQL API using a microservices architecture.
 ---
 
 ## What is Apollo Federation?

diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx
@@ -1,7 +1,7 @@
 ---
-title: Deployment best practices
+title: Deployment Best Practices
 subtitle: Best practices and workflows for deploying with managed federation
-description: Best practices and workflows for deploying with managed federation
+description: Best practices and workflows for deploying a federated GraphQL API with Apollo Federation and GraphOS.
 ---
 
 When rolling out changes to a [subgraph](../building-supergraphs/subgraphs-overview/), we recommend the following workflow:

diff --git a/docs/source/managed-federation/error-reporting.mdx b/docs/source/managed-federation/error-reporting.mdx
@@ -1,5 +1,7 @@
 ---
-title: Opt-in error reporting for managed federation
+title: Opt-In Error Reporting for Managed Federation
+subtitle: Configure out-of-band reporting
+description: Learn how to configure your managed gateway to send error reports to Apollo via out-of-band reporting, improving performance and reliability.
 ---
 
 You can configure your managed gateway to send error reports to Apollo via _out-of-band reporting_. These reports help Apollo improve the performance and reliability of managed federation.

diff --git a/docs/source/managed-federation/federated-schema-checks.mdx b/docs/source/managed-federation/federated-schema-checks.mdx
@@ -1,5 +1,7 @@
 ---
-title: Federated schema checks
+title: Federated Schema Checks
+subtitle: Use schema checks for independent and safe subgraph development
+description: Use GraphOS schema checks and the Rover CLI to enable independent and safe subgraph development in federated GraphQL architectures.
 ---
 
 <Tip>

diff --git a/docs/source/managed-federation/overview.mdx b/docs/source/managed-federation/overview.mdx
@@ -1,7 +1,7 @@
 ---
-title: Managed federation overview
-description: Let Apollo GraphOS manage CI/CD of your supergraph including schema validation, composition, and configuration.
+title: Managed Federation Overview
 subtitle: Manage supergraph CI/CD with Apollo GraphOS
+description: Use Apollo GraphOS to manage your supergraph including schema validation, composition, and configuration.
 ---
 
 import ManagedFederationDiagram from '../../shared/diagrams/managed-federation.mdx';

diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx
@@ -1,5 +1,7 @@
 ---
-title: Setting up managed federation
+title: Setting Up Managed Federation
+subtitle: Connect your supergraph to Apollo GraphOS
+description: Learn how to connect your supergraph to the Apollo GraphOS platform for managed GraphQL federation.
 ---
 
 This article describes how to connect your supergraph to [Apollo GraphOS](/graphos/) to enable managed federation features.

diff --git a/docs/source/managed-federation/uplink.mdx b/docs/source/managed-federation/uplink.mdx
@@ -1,6 +1,7 @@
 ---
 title: Apollo Uplink
-description: Fetch your managed router's configuration
+subtitle: Fetch your managed router's configuration
+description: Learn how to configure Apollo Uplink for managed GraphQL federation, including polling behavior and Uplink URLs.
 ---
 
 When using [managed federation](./overview/), your supergraph's router by default regularly polls an endpoint called _Apollo Uplink_ for its latest supergraph schema and other configuration:

diff --git a/docs/source/metrics.md b/docs/source/metrics.md
@@ -1,6 +1,7 @@
 ---
-title: Federated trace data
-description: Reporting fine-grained performance metrics
+title: Federated Trace Data
+subtitle: Reporting fine-grained performance metrics
+description: Explore how federated traces enable fine-grained performance metrics reporting. Learn about the reporting flow and how tracing data is exposed and aggregated.
 ---
 
 One of the many benefits of using GraphQL as an API layer is that it enables fine-grained, field-level [tracing](/graphos/metrics/#resolver-level-traces) of every executed operation. The [GraphOS platform](/graphos/) can consume and aggregate these traces to provide detailed insights into your supergraph's usage and performance.

diff --git a/docs/source/migrating-from-stitching.md b/docs/source/migrating-from-stitching.md
@@ -1,6 +1,7 @@
 ---
-title: Migrating from schema stitching
-description: How to move your services to Apollo Federation
+title: Migrating from Schema Stitching
+subtitle: How to transition to Apollo Federation
+description: Learn how to smoothly transition from schema stitching to Apollo Federation for your distributed federated GraphQL services.
 ---
 
 If you have a distributed graph that uses schema stitching, follow the

diff --git a/docs/source/opentelemetry.mdx b/docs/source/opentelemetry.mdx
@@ -1,6 +1,8 @@
 ---
 title: OpenTelemetry in Apollo Federation
 sidebar_title: OpenTelemetry
+subtitle: Configure your federated graph to emit logs, traces, and metrics
+description: Learn how to configure your federated GraphQL services to generate and process telemetry data, including logs, traces, and metrics.
 ---
 
 [OpenTelemetry](https://opentelemetry.io/) is a collection of open-source tools for generating and processing telemetry data (such as logs, traces, and metrics) from different systems in a generic and consistent way.

diff --git a/docs/source/performance/caching.mdx b/docs/source/performance/caching.mdx
@@ -1,6 +1,8 @@
 ---
-title: Server-side caching
+title: Server-Side Caching
 sidebar_title: Caching
+subtitle: Configure server-side caching with Apollo Server-based subgraphs
+description: Learn about implementing server-side caching in a federated GraphQL architecture, including using and overriding cache hints with subgraphs.
 ---
 
 <Note>

diff --git a/docs/source/performance/monitoring.mdx b/docs/source/performance/monitoring.mdx
@@ -1,6 +1,8 @@
 ---
-title: Monitoring a federated graph
+title: Monitoring a Federated Graph
 sidebar_title: Monitoring
+subtitle: Learn about operation metrics and monitoring strategies
+description: Discover Apollo managed federation features that enhance monitoring and debugging capabilities for your federated GraphQL API.
 ---
 
 As with any distributed architecture, a federated graph introduces more complexity than its monolithic counterpart. To help address this complexity and improve reliability, you should make sure that your federated graph has proper observability, monitoring, and automation in place.

diff --git a/docs/source/query-plans.mdx b/docs/source/query-plans.mdx
@@ -1,6 +1,7 @@
 ---
-title: Query plans
-description: How your router plans operations across subgraphs
+title: Query Plans
+subtitle: Learn how your router orchestrates operations across subgraphs
+description: Learn how your router orchestrates operations across subgraphs, ensuring seamless data retrieval for complex GraphQL operations in a federated architecture.
 ---
 
 Learn about query plans to help you debug advanced use cases of Apollo Federation.