docs: cleanup and fixes (#4419)

This PR has some cleanup tasks:
- Reorganized the information architecture a bit so that sections flow
better
- Fixed broken links
- Fixed a code snippet that wasn't closed off/bleeding into a section
- Updated auth strategy guide w/ callouts for not using resolver auth in
production per @benjie request

Please let me know if there are any other tweaks I can include!

---------

Co-authored-by: Benjie <[email protected]>
Co-authored-by: Jovi De Croock <[email protected]>

Author: 3 people

website/pages/docs/_meta.ts

@@ -2,44 +2,44 @@ const meta = {
   index: '',
   '-- 1': {
     type: 'separator',
-    title: 'GraphQL.JS Tutorial',
+    title: 'Getting Started',
   },
   'getting-started': '',
   'running-an-express-graphql-server': '',
   'graphql-clients': '',
+  'authentication-and-express-middleware': '',
+  '-- 2': {
+    type: 'separator',
+    title: 'Core Concepts',
+  },
   'basic-types': '',
   'passing-arguments': '',
   'object-types': '',
   'mutations-and-input-types': '',
-  'authentication-and-express-middleware': '',
-  'authorization-strategies': '',
-  '-- 2': {
+  nullability: '',
+  'abstract-types': '',
+  'custom-scalars': '',
+  '-- 3': {
     type: 'separator',
     title: 'Advanced Guides',
   },
   'constructing-types': '',
-  nullability: '',
-  'abstract-types': '',
   'oneof-input-objects': '',
   'defer-stream': '',
   subscriptions: '',
   'type-generation': '',
   'cursor-based-pagination': '',
-  'custom-scalars': '',
   'advanced-custom-scalars': '',
   'operation-complexity-controls': '',
   'n1-dataloader': '',
   'caching-strategies': '',
   'resolver-anatomy': '',
   'graphql-errors': '',
   'using-directives': '',
-  '-- 3': {
-    type: 'separator',
-    title: 'Testing',
-  },
+  'authorization-strategies': '',
   '-- 4': {
     type: 'separator',
-    title: 'FAQ',
+    title: 'Production & Scaling',
   },
   'going-to-production': '',
   'scaling-graphql': '',

website/pages/docs/abstract-types.mdx

@@ -2,6 +2,8 @@
 title: Abstract types in GraphQL.js
 ---
 
+# Abstract types in GraphQL.js
+
 GraphQL includes two kinds of abstract types: interfaces and unions. These types let a single
 field return values of different object types, while keeping your schema type-safe.
 
@@ -206,7 +208,7 @@ union in future, and thus ensure that you have a default case to handle addition
 
 ## Additional resources
 
-- [Constructing Types](https://www.graphql-js.org/docs/constructing-types/)
+- [Constructing Types](./constructing-types)
 - GraphQL Specification:
   - [Interfaces](https://spec.graphql.org/October2021/#sec-Interfaces)
   - [Unions](https://spec.graphql.org/October2021/#sec-Unions)

website/pages/docs/authentication-and-express-middleware.mdx

@@ -3,6 +3,8 @@ title: Using Express Middleware with GraphQL.js
 sidebarTitle: Using Express Middleware
 ---
 
+# Authentication and Express Middleware
+
 import { Tabs } from 'nextra/components';
 
 It's simple to use any Express middleware in conjunction with `graphql-http`. In particular, this is a great pattern for handling authentication.
@@ -101,4 +103,4 @@ If you aren't familiar with any of these authentication mechanisms, we recommend
 
 If you've read through the docs linearly to get to this point, congratulations! You now know everything you need to build a practical GraphQL API server.
 
-Want to control access to specific operations or fields? See [Authorization Strategies](\pages\docs\authorization-strategies.mdx).
+Want to control access to specific operations or fields? See [Authorization Strategies](./authorization-strategies).

website/pages/docs/authorization-strategies.mdx

@@ -2,6 +2,8 @@
 title: Authorization Strategies
 ---
 
+import { Callout } from 'nextra/components'
+
 GraphQL gives you complete control over how to define and enforce access control. 
 That flexibility means it's up to you to decide where authorization rules live and 
 how they're enforced.
@@ -10,6 +12,12 @@ This guide covers common strategies for implementing authorization in GraphQL
 servers using GraphQL.js. It assumes you're authenticating requests and passing a user or 
 session object into the `context`.
 
+<Callout type="info" emoji="ℹ️">
+  In production systems authorization should be handled in your business logic layer, not your
+  GraphQL resolvers. GraphQL is intended to be a thin execution layer that calls into your application's
+  domain logic, which enforces access control.
+</Callout>
+
 ## What is authorization?
 
 Authorization determines what a user is allowed to do. It's different from 
@@ -23,11 +31,7 @@ In GraphQL, authorization typically involves restricting:
 
 ## Resolver-based authorization
 
-> **Note:**  
-> All examples assume you're using Node.js 20 or later with [ES module (ESM) support](https://nodejs.org/api/esm.html) enabled.
-
-The simplest approach is to enforce access rules directly inside resolvers 
-using the `context.user` value:
+You can implement simple authorization checks directly in resolvers using `context.user`:
 
 ```js
 export const resolvers = {
@@ -42,12 +46,15 @@ export const resolvers = {
 };
 ```
 
-This works well for smaller schemas or one-off checks.
+This approach can help when you're learning how context works or building quick prototypes.
+However, for production systems, you should enforce access control in your business logic layer 
+rather than in GraphQL resolvers.
 
 ## Centralizing access control logic
 
-As your schema grows, repeating logic like `context.user.role !=='admin'`
-becomes error-prone. Instead, extract shared logic into utility functions:
+If you're experimenting or building a small project, repeating checks like 
+`context.user.role !== 'admin'` across resolvers can become error-prone. One 
+way to manage that duplication is by extracting shared logic into utility functions:
 
 ```js
 export function requireUser(user) {
@@ -64,7 +71,7 @@ export function requireRole(user, role) {
 }
 ```
 
-You can use these helpers in resolvers:
+Then use those helpers in resolvers:
 
 ```js
 import { requireRole } from './auth.js';
@@ -79,7 +86,11 @@ export const resolvers = {
 };
 ```
 
-This pattern makes your access rules easier to read, test, and update.
+This pattern improves readability and reusability, but like all resolver-based authorization, 
+it's best suited for prototypes or early-stage development.
+
+For production use, move authorization into your business logic layer. These helpers can still be useful 
+there, but they should be applied outside the GraphQL execution layer.
 
 ## Field-level access control
 
@@ -148,8 +159,7 @@ resolver-based checks and adopt directives later if needed.
 
 ## Best practices
 
-- Keep authorization logic close to business logic. Resolvers are often the
-right place to keep authorization logic.
+- Keep authorization logic in your business logic layer, not in your GraphQL resolvers.
 - Use shared helper functions to reduce duplication and improve clarity.
 - Avoid tightly coupling authorization logic to your schema. Make it
 reusable where possible.

website/pages/docs/basic-types.mdx

@@ -2,6 +2,8 @@
 title: Basic Types
 ---
 
+# Basic Types
+
 import { Tabs } from 'nextra/components';
 
 In most situations, all you need to do is to specify the types for your API using the GraphQL schema language, taken as an argument to the `buildSchema` function.

website/pages/docs/caching-strategies.mdx

@@ -142,7 +142,7 @@ export const resolvers = {
 - This isn't a long-lived cache. Combine it with other layers for broader coverage.
 
 To read more about DataLoader and the N+1 problem,
-see [Solving the N+1 Problem with DataLoader](https://github.com/graphql/dataloader).
+see [Solving the N+1 Problem with DataLoader](./n1-dataloader).
 
 ## Operation result caching
 

website/pages/docs/constructing-types.mdx

@@ -2,6 +2,8 @@
 title: Constructing Types
 ---
 
+# Constructing Types
+
 import { Tabs } from 'nextra/components';
 
 For many apps, you can define a fixed schema when the application starts, and define it using GraphQL schema language. In some cases, it's useful to construct a schema programmatically. You can do this using the `GraphQLSchema` constructor.

website/pages/docs/cursor-based-pagination.mdx

@@ -4,6 +4,8 @@ title: Implementing Cursor-based Pagination
 
 import { Callout } from "nextra/components";
 
+# Implementing Cursor-based Pagination
+
 When a GraphQL API returns a list of data, pagination helps avoid
 fetching too much data at once. Cursor-based pagination fetches items
 relative to a specific point in the list, rather than using numeric offsets.

website/pages/docs/defer-stream.mdx

@@ -2,6 +2,8 @@
 title: Enabling Defer & Stream
 ---
 
+# Enabling Defer and Stream
+
 import { Callout } from 'nextra/components'
 
 <Callout type="info" emoji="ℹ️">

website/pages/docs/going-to-production.mdx

@@ -2,8 +2,11 @@
 title: Going to Production
 ---
 
-Bringing a GraphQL.js server into production involves more than deploying code. In production,
-a GraphQL server should be secure, fast, observable, and protected against abusive queries.
+# Going to Production
+
+GraphQL.JS contains a few development checks which in production will cause slower performance and
+an increase in bundle-size. Every bundler goes about these changes different, in here we'll list
+out the most popular ones.
 
 GraphQL.js includes development-time checks that are useful during local testing but should
 be disabled in production to reduce overhead. Additional concerns include caching, error handling,