From 96e31bb3dbdba22d7f614dbd1a85c97b676f0158 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 12 Nov 2026 01:05:27 +0000 Subject: [PATCH 1/2] Document kebab-case GraphQL URLs and scalar type pages Co-authored-by: brandon --- api-playground/graphql-setup.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/api-playground/graphql-setup.mdx b/api-playground/graphql-setup.mdx index 0ae3abbc24..a3ec8c70bc 100644 --- a/api-playground/graphql-setup.mdx +++ b/api-playground/graphql-setup.mdx @@ -92,10 +92,12 @@ Mintlify organizes generated pages into three sections under the tab or group yo - **Queries**: One page per field on your `Query` root type. - **Mutations**: One page per field on your `Mutation` root type. -- **Types**: One page per named object, input, enum, interface, or union type. +- **Types**: One page per named object, input, enum, interface, union, or custom scalar type. On a tab, the sections appear after any groups you define. On a group, they appear as nested groups after any pages you list. +Page URLs use kebab case, and type pages are grouped by kind. For example, the `Cart` object is at `graphql-reference/types/objects/cart` and the `DateTime` scalar is at `graphql-reference/types/scalars/date-time`. If two names of the same kind produce the same URL, such as `FooBar` and `fooBar`, Mintlify adds a short suffix to each URL to keep them apart. URLs that use the earlier format, such as `graphql-reference/types/Cart`, redirect to the new URLs. + Each operation page shows the field description, arguments, return type, and links to any referenced types. Query and mutation pages also include a generated example operation, the required variables, and a sample JSON response. Type pages render the schema definition read-only, with linked field types so readers can navigate the graph. @@ -133,11 +135,11 @@ A selector is a kind followed by a name, separated by a space: - `QUERY `: A field on your `Query` root type. - `MUTATION `: A field on your `Mutation` root type. -- `TYPE `: A named object, input, enum, interface, or union type. +- `TYPE `: A named object, input, enum, interface, union, or custom scalar type. Selector kinds must be uppercase. Use a dotted path, such as `MUTATION cart.createCart`, to select an operation nested under a namespace field. `TYPE` selectors do not accept dotted paths. -The sidebar labels a nested operation with its last segment, so `MUTATION cart.createCart` appears as `createCart`. The page URL keeps the full path and ends in `cart/createCart`. +The sidebar labels a nested operation with its last segment, so `MUTATION cart.createCart` appears as `createCart`. The page URL keeps the full path and ends in `cart/create-cart`. If any page under a tab or group with `graphql` is a selector, Mintlify skips generating the full **Queries**, **Mutations**, and **Types** sections for it. Regular page paths in the same `pages` array work as usual. From a288ff35161724fb02023fbc34e156e2c7f99677 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 12 Nov 2026 02:43:10 +0000 Subject: [PATCH 2/2] Describe collision-only GraphQL URLs Co-authored-by: brandon --- api-playground/graphql-setup.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-playground/graphql-setup.mdx b/api-playground/graphql-setup.mdx index a3ec8c70bc..6793b0bf58 100644 --- a/api-playground/graphql-setup.mdx +++ b/api-playground/graphql-setup.mdx @@ -96,7 +96,7 @@ Mintlify organizes generated pages into three sections under the tab or group yo On a tab, the sections appear after any groups you define. On a group, they appear as nested groups after any pages you list. -Page URLs use kebab case, and type pages are grouped by kind. For example, the `Cart` object is at `graphql-reference/types/objects/cart` and the `DateTime` scalar is at `graphql-reference/types/scalars/date-time`. If two names of the same kind produce the same URL, such as `FooBar` and `fooBar`, Mintlify adds a short suffix to each URL to keep them apart. URLs that use the earlier format, such as `graphql-reference/types/Cart`, redirect to the new URLs. +Page URLs use each name as written, such as `graphql-reference/types/Cart`. If two names differ only by case, such as `StoreFrontConfigType` and `StorefrontConfigType`, the name that sorts first keeps that URL and the other uses a kebab-case URL, such as `graphql-reference/types/storefront-config-type`. The build logs a warning for each name that gets a new URL. Each operation page shows the field description, arguments, return type, and links to any referenced types. Query and mutation pages also include a generated example operation, the required variables, and a sample JSON response. @@ -139,7 +139,7 @@ A selector is a kind followed by a name, separated by a space: Selector kinds must be uppercase. Use a dotted path, such as `MUTATION cart.createCart`, to select an operation nested under a namespace field. `TYPE` selectors do not accept dotted paths. -The sidebar labels a nested operation with its last segment, so `MUTATION cart.createCart` appears as `createCart`. The page URL keeps the full path and ends in `cart/create-cart`. +The sidebar labels a nested operation with its last segment, so `MUTATION cart.createCart` appears as `createCart`. The page URL keeps the full path and ends in `cart/createCart`. If any page under a tab or group with `graphql` is a selector, Mintlify skips generating the full **Queries**, **Mutations**, and **Types** sections for it. Regular page paths in the same `pages` array work as usual.