chore: align reference headings, descriptions, structure (#1815)

Co-authored-by: Alexis Aguilar <[email protected]>
clerk · Dec 19, 2024 · a6f8eef · a6f8eef
1 parent 0635023
commit a6f8eef
Show file tree

Hide file tree

Showing 11 changed files with 44 additions and 66 deletions.
diff --git a/docs/references/astro/overview.mdx b/docs/references/astro/overview.mdx
@@ -1,9 +1,9 @@
 ---
 title: Clerk Astro SDK
-description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your Astro application.
+description: Learn how to integrate Clerk into your Astro application using the Clerk Astro SDK.
 ---
 
-Clerk makes it simple to add authentication to your Astro application. This documentation covers the capabilities and methods available from Clerk's Astro SDK.
+The Clerk Astro SDK is the recommended method for integrating Clerk into your Astro application.
 
 ## Guides
 
@@ -12,7 +12,7 @@ Clerk makes it simple to add authentication to your Astro application. This docu
 
 ## Client-side helpers
 
-Clerk Astro provides a set of useful [stores](https://github.com/nanostores/nanostores) that give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, and helper methods for signing in and signing up.
+The Astro SDK provides [stores](https://github.com/nanostores/nanostores) that give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object and helper methods for authentication flows.
 
 - [`$authStore`](/docs/references/astro/auth-store)
 - [`$clerkStore`](/docs/references/astro/clerk-store)
@@ -23,9 +23,18 @@ Clerk Astro provides a set of useful [stores](https://github.com/nanostores/nano
 - [`$sessionListStore`](/docs/references/astro/session-list-store)
 - [`$organizationStore`](/docs/references/astro/organization-store)
 
-## General Reference
+## Server-side helpers
 
-### `Auth` object
+The following references show how to integrate Clerk features into your Astro app on the server-side.
+
+### Locals
+
+The Astro SDK provides access to Clerk's authentication data through Astro's [`locals`](https://docs.astro.build/en/guides/middleware/#storing-data-in-contextlocals) object. The following references show how to access authentication data in server-side code:
+
+- [Auth](/docs/references/astro/locals#auth)
+- [CurrentUser](/docs/references/astro/locals#currentuser)
+
+#### `Auth` object
 
 `Astro.locals.auth()` returns an `Auth` object. This JavaScript object contains important information like session data, your user's ID, as well as their active organization ID. Learn more about the `Auth` object [here](/docs/references/nextjs/auth-object){{ target: '_blank' }}.
 

diff --git a/docs/references/chrome-extension/overview.mdx b/docs/references/chrome-extension/overview.mdx
@@ -1,9 +1,9 @@
 ---
 title: Clerk Chrome Extension SDK 
-description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your Chrome Extension.
+description: Learn how to integrate Clerk into your Chrome Extension using the Clerk Chrome Extension SDK.
 ---
 
-Clerk provides a Chrome Extension SDK that allows you to easily integrate Clerk into your Chrome Extension. This SDK provides a simple way to authenticate users and manage their sessions.
+The Clerk Chrome Extension SDK is the recommended method for integrating Clerk into your Chrome Extension.
 
 ## Authentication options
 

diff --git a/docs/references/expo/overview.mdx b/docs/references/expo/overview.mdx
@@ -1,9 +1,9 @@
 ---
 title: Clerk Expo SDK
-description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your Expo application.
+description: Learn how to integrate Clerk into your Expo application using the Clerk Expo SDK.
 ---
 
-Clerk makes it simple to add authentication to your Expo app. This documentation covers the capabilities and methods available from Clerk's Expo SDK.
+The Clerk Expo SDK is the recommended method for integrating Clerk into your Expo application.
 
 See [the quickstart](/docs/quickstarts/expo) to get started.
 

diff --git a/docs/references/express/overview.mdx b/docs/references/express/overview.mdx
@@ -1,9 +1,9 @@
 ---
 title: Clerk Express SDK
-description: Learn how to integrate Express into your Clerk application.
+description: Learn how to integrate Clerk into your Express application using the Clerk Express SDK.
 ---
 
-Clerk makes it simple to add authentication to your Express application. This documentation covers the capabilities and methods available from Clerk's Express SDK.
+The Clerk Express SDK is the recommended method for integrating Clerk into your Express application.
 
 See the [quickstart](/docs/quickstarts/express) to get started.
 
@@ -12,7 +12,7 @@ See the [quickstart](/docs/quickstarts/express) to get started.
 > [!IMPORTANT]
 > If you are upgrading from the Node SDK, see the [upgrade guide](/docs/upgrade-guides/node-to-express) for more information.
 
-## Available methods
+## Methods
 
 ### `clerkMiddleware()`
 

diff --git a/docs/references/go/overview.mdx b/docs/references/go/overview.mdx
@@ -1,9 +1,9 @@
 ---
 title: Clerk Go SDK
-description: Learn how to integrate Go into your Clerk application.
+description: Learn how to integrate Clerk into your Go application using the Clerk Go SDK.
 ---
 
-The [Clerk Go SDK](https://github.com/clerk/clerk-sdk-go) is a wrapper over the [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }}.
+The Clerk Go SDK is built on top of the [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }}.
 
 ## Installation
 

diff --git a/docs/references/ios/overview.mdx b/docs/references/ios/overview.mdx
@@ -1,12 +1,12 @@
 ---
 title: Clerk iOS SDK (Beta)
-description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your iOS application.
+description: Learn how to integrate Clerk into your iOS application using the Clerk iOS SDK.
 ---
 
 > [!WARNING]
 > The Clerk iOS SDK is currently in beta. It is **not yet recommended for production use**.
 
-Clerk makes it simple to add authentication to your iOS application. This documentation covers the capabilities and methods available from Clerk's iOS SDK.
+The Clerk iOS SDK is the recommended method for integrating Clerk into your iOS application.
 
 See [the quickstart](/docs/quickstarts/ios) to get started.
 

diff --git a/docs/references/nextjs/overview.mdx b/docs/references/nextjs/overview.mdx
@@ -1,13 +1,13 @@
 ---
 title: Clerk Next.js SDK
-description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your Next.js application.
+description: Learn how to integrate Clerk into your Next.js application using the Clerk Next.js SDK.
 ---
 
-Clerk makes it simple to add authentication to your Next.js application. This reference lists the features and methods available in Clerk's Next.js SDK.
+The Clerk Next.js SDK is the recommended method for integrating Clerk into your Next.js application.
 
 ## Client-side helpers
 
-Because the Next.js SDK is built on top of the Clerk React SDK, you can utilize the hooks that the React SDK provides. These hooks give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object and a set of useful helper methods for signing in and signing up. Learn more about these hooks in the [React SDK reference](/docs/references/react/overview).
+Because the Next.js SDK is built on top of the Clerk React SDK, you can use the hooks that the React SDK provides. These hooks give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object and a set of useful helper methods for signing in and signing up. Learn more in the [React SDK reference](/docs/references/react/overview).
 
 <Include src="_partials/react-hooks" />
 
@@ -29,19 +29,17 @@ Clerk continues to provide drop-in support for the Next.js Pages Router. In addi
 - [`getAuth()`](/docs/references/nextjs/get-auth)
 - [`buildClerkProps()`](/docs/references/nextjs/build-clerk-props)
 
-## Other references
-
-### `Auth` object
+## `Auth` object
 
 Both `auth()` (App Router) and `getAuth()` (Pages Router) return an `Auth` object. This JavaScript object contains important information like the current user's session ID, user ID, and organization ID. Learn more about the [`Auth` object](/docs/references/nextjs/auth-object){{ target: '_blank' }}.
 
-### `clerkMiddleware()`
+## `clerkMiddleware()`
 
 The `clerkMiddleware()` helper integrates Clerk authentication into your Next.js application through middleware. It allows you to integrate authorization into both the client and server of your application. You can learn more [here](/docs/references/nextjs/clerk-middleware).
 
-### Demo repositories
+## Demo repositories
 
-To see an example of Clerk's features, such as user and organization management, integrated in a single application, explore the Clerk + Next.js demo repositories:
+For examples of Clerk's features, such as user and organization management, integrated into a single application, see the Next.js demo repositories:
 
 - [Clerk + Next.js App Router Demo](https://github.com/clerk/clerk-nextjs-demo-app-router)
 - [Clerk + Next.js Pages Router Demo](https://github.com/clerk/clerk-nextjs-demo-pages-router)
diff --git a/docs/references/react-router/overview.mdx b/docs/references/react-router/overview.mdx
@@ -1,16 +1,16 @@
 ---
 title: Clerk React Router SDK
-description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your React Router application.
+description: Learn how to integrate Clerk into your React Router application using the Clerk React Router SDK.
 ---
 
 > [!WARNING]
 > The React Router SDK is currently in beta.
 
-Clerk makes it simple to add authentication to your React Router application. This reference lists the features and methods available in Clerk's React Router SDK.
+The Clerk React Router SDK is built on top of the [React SDK](/docs/references/react/overview) and is the recommended method for integrating Clerk into your React Router application.
 
 ## Client-side helpers
 
-The Clerk React Router SDK is built on top of the Clerk React SDK and provides access to all of Clerk React's hooks. These hooks give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object and a set of useful helper methods for signing in and signing up. Learn more about these hooks in the [React SDK reference](/docs/references/react/overview).
+The React Router SDK provides access to all of Clerk React's hooks which give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object and a set of useful helper methods for signing in and signing up. Learn more in the [React SDK reference](/docs/references/react/overview).
 
 <Include src="_partials/react-hooks" />
 

diff --git a/docs/references/react/overview.mdx b/docs/references/react/overview.mdx
@@ -3,11 +3,11 @@ title: Clerk React SDK
 description: Learn how to integrate Clerk into your React application using the Clerk React SDK.
 ---
 
-The React SDK is built on top of the JavaScript SDK, and is the recommended method for integrating Clerk into your React application.
+The Clerk React SDK is built on top of the [JavaScript SDK](/docs/references/javascript/overview) and is the recommended method for integrating Clerk into your React application.
 
 ## Custom hooks
 
-The React SDK provides access to custom hooks that provide direct access to the [`Clerk` object](/docs/references/javascript/clerk/clerk), a user's [`User` object](/docs/references/javascript/user/user), and helper methods for authentication flows.
+The React SDK provides hooks that give you access to the [`Clerk` object](/docs/references/javascript/clerk/clerk), [`User` object](/docs/references/javascript/user/user), and helper methods for authentication flows.
 
 <Include src="_partials/react-hooks" />
 

diff --git a/docs/references/redwood/overview.mdx b/docs/references/redwood/overview.mdx
@@ -1,9 +1,9 @@
 ---
 title: Clerk RedwoodJS SDK
-description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your RedwoodJS application.
+description: Learn how to integrate Clerk into your RedwoodJS application using the Clerk RedwoodJS SDK.
 ---
 
-Learn how to use Clerk to quickly and easily add secure authentication and user management to your RedwoodJS application.
+The Clerk RedwoodJS SDK is the recommended method for integrating Clerk into your RedwoodJS application.
 
 <Steps>
   ## Create a RedwoodJS application
@@ -104,22 +104,3 @@ Learn how to use Clerk to quickly and easily add secure authentication and user
   }
   ```
 </Steps>
-
-## Next steps
-
-Now that you have an application integrated with Clerk, you will want to read the following documentation:
-
-<Cards>
-  - [Customization & Localization](/docs/customization/overview)
-  - Learn how to customize and localize the Clerk components.
-
-  ---
-
-  - [Authentication Components](/docs/components/authentication/sign-in)
-  - Learn more about all our authentication components.
-
-  ---
-
-  - [Client Side Helpers](/docs/references/react/use-user)
-  - Learn more about our client-side helpers and how to use them.
-</Cards>
diff --git a/docs/references/tanstack-start/overview.mdx b/docs/references/tanstack-start/overview.mdx
@@ -1,9 +1,9 @@
 ---
 title: Clerk TanStack Start SDK
-description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your TanStack Start application.
+description: Learn how to integrate Clerk into your TanStack Start application using the Clerk TanStack Start SDK.
 ---
 
-Clerk makes it simple to add authentication to your TanStack Start application. This documentation covers the capabilities and methods available for Clerk's TanStack SDK.
+The Clerk TanStack Start SDK is built on top of the [React SDK](/docs/references/react/overview) and is the recommended method for integrating Clerk into your TanStack Start application.
 
 ## Guides
 
@@ -12,23 +12,13 @@ Clerk makes it simple to add authentication to your TanStack Start application.
 
 ## Client-side helpers
 
-Because Clerk TanStack Start is a wrapper around Clerk React, you can utilize the hooks that Clerk React provides. These hooks give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, and a set of useful helper methods for signing in and signing up. You can learn more about these hooks [in the React SDK reference](/docs/references/react/overview).
+The TanStack Start SDK is a wrapper around Clerk React, so you can use the hooks that Clerk React provides. These hooks give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, and a set of useful helper methods for signing in and signing up. Learn more in the [React SDK reference](/docs/references/react/overview).
 
-{/* TODO: We can use a partial here. */}
-
-- [`useUser()`](/docs/references/react/use-user)
-- [`useClerk()`](/docs/references/react/use-clerk)
-- [`useAuth()`](/docs/references/react/use-auth)
-- [`useSignIn()`](/docs/references/react/use-sign-in)
-- [`useSignUp()`](/docs/references/react/use-sign-up)
-- [`useSession()`](/docs/references/react/use-session)
-- [`useSessionList()`](/docs/references/react/use-session-list)
-- [`useOrganization()`](/docs/references/react/use-organization)
-- [`useOrganizationList()`](/docs/references/react/use-organization-list)
+<Include src="_partials/react-hooks" />
 
 ## Server-side helpers
 
-The below methods and references show how to integrate Clerk features into applications that take advantage of TanStack Start server functions and API routes.
+The following references show how to integrate Clerk features into applications using TanStack Start server functions and API routes.
 
 - [`getAuth()`](/docs/references/tanstack-start/get-auth)