Embed tooltips in to docs

CONTRIBUTING.md

@@ -745,6 +745,20 @@ The video below shows what this example looks like once rendered.
 
 https://github.com/clerk/clerk-docs/assets/2615508/9b07ba1d-8bb0-498b-935f-432d2d047ab6
 
+### Tooltips
+
+A tooltip is content that appears when the user hovers over a word or phrase in order to provide additional information. A common use case is for definitions.
+
+Tooltips are defined in the `_tooltips` folder and written in MDX, but they do not support custom MDX components, like callouts or `<Tabs />` components. Try to keep the tooltip content as text.
+
+The tooltip syntax is similar to a link, but with a `!` prefix, as shown in the following example:
+
+```mdx
+The ID of the [active organization](!active-organization) that the user belongs to.
+```
+
+Tooltips should follow the same styleguide as links - only add them on the first mention of a term and only in the highest heading section. So if a term is mentioned in an H2 section and again in its H3 section, it doesn't need to be added in the H3 section.
+
 ### `<TutorialHero />`
 
 The `<TutorialHero />` component is used at the beginning of a tutorial-type content page. It accepts the following properties:

docs/_partials/clerk-middleware-options.mdx

@@ -46,7 +46,7 @@ The `clerkMiddleware()` function accepts an optional object. The following optio
   - `organizationSyncOptions?`
   - <code>[OrganizationSyncOptions](#organization-sync-options) | undefined</code>
 
-  Used to activate a specific [organization](/docs/organizations/overview) or [personal account](/docs/organizations/overview#allow-personal-accounts) based on URL path parameters. If there's a mismatch between the active organization in the session (e.g., as reported by [`auth()`](/docs/references/nextjs/auth)) and the organization indicated by the URL, the middleware will attempt to activate the organization specified in the URL.
+  Used to activate a specific [organization](/docs/organizations/overview) or [personal account](/docs/organizations/overview#allow-personal-accounts) based on URL path parameters. If there's a mismatch between the [active organization](!active-organization) in the session (e.g., as reported by [`auth()`](/docs/references/nextjs/auth)) and the organization indicated by the URL, the middleware will attempt to activate the organization specified in the URL.
 
   ---
 

docs/_tooltips/active-organization.mdx

@@ -0,0 +1 @@
+A user can be a member of multiple organizations, but only one can be active at a time. The **active organization** determines which organization-specific data the user can access and which role and related permissions they have within the organization.

docs/backend-requests/resources/session-tokens.mdx

@@ -76,10 +76,10 @@ Read more about Clerk session tokens and how they work in [the guide on how Cler
 
     | Claim | Abbreviation expanded | Description | Example |
     | - | - | - | - |
-    | `org_id` | organization ID | The ID of the active organization that the user belongs to. | `org_123` |
-    | `org_permissions` | organization permissions | The permissions of the user in the currently active organization. System permissions are not included in the session token. | `["org:admin:example_permission", "org:member:example_permission"]` |
-    | `org_slug` | organization slug | The slug of the currently active organization that the user belongs to. | `org-slug` |
-    | `org_role` | organization role | The role of the user in the currently active organization. | `org:admin` |
+    | `org_id` | organization ID | The ID of the [active organization](!active-organization) that the user belongs to. | `org_123` |
+    | `org_permissions` | organization permissions | The permissions of the user in the currently [active organization](!active-organization). System permissions are not included in the session token. | `["org:admin:example_permission", "org:member:example_permission"]` |
+    | `org_slug` | organization slug | The slug of the currently [active organization](!active-organization) that the user belongs to. | `org-slug` |
+    | `org_role` | organization role | The role of the user in the currently [active organization](!active-organization). | `org:admin` |
 
     The **`act` (actor) claim** is only included if the user is [impersonating](/docs/users/user-impersonation) another user. It's value is an object that contains the following properties:
 

docs/components/billing/checkout-button.mdx

@@ -78,7 +78,7 @@ The `<CheckoutButton />` component renders a button that opens the checkout draw
 </>
 ```
 
-`<CheckoutButton />` will throw an error if the `for` prop is set to `'organization'` and no [active organization](/docs/organizations/overview#active-organization) is set.
+`<CheckoutButton />` will throw an error if the `for` prop is set to `'organization'` and no [active organization](!active-organization) is set.
 
 ```tsx
 <>

docs/components/billing/subscription-details-button.mdx

@@ -59,7 +59,7 @@ All props are optional.
 </>
 ```
 
-`<SubscriptionDetailsButton />` will throw an error if the `for` prop is set to `'organization'` and no [active organization](/docs/organizations/overview#active-organization) is set.
+`<SubscriptionDetailsButton />` will throw an error if the `for` prop is set to `'organization'` and no [active organization](!active-organization) is set.
 
 ```tsx
 <>

docs/components/organization/organization-switcher.mdx

@@ -23,7 +23,7 @@ The `<OrganizationSwitcher />` component accepts the following properties, all o
   - `afterLeaveOrganizationUrl`
   - `string`
 
-  The full URL or path to navigate to after the user leaves the currently active organization.
+  The full URL or path to navigate to after the user leaves the currently [active organization](!active-organization).
 
   ---
 

docs/custom-flows/manage-membership-requests.mdx

@@ -11,7 +11,7 @@ This guide will demonstrate how to use the Clerk API to build a custom flow for
   <Tab>
     The following example:
 
-    1. Uses the [`useOrganization()`](/docs/hooks/use-organization) hook to get `membershipRequests`, which is a list of the active organization's membership requests.
+    1. Uses the [`useOrganization()`](/docs/hooks/use-organization) hook to get `membershipRequests`, which is a list of the [active organization's](!active-organization) membership requests.
        - `membershipRequests` is an object with `data` that contains an array of [`OrganizationMembershipRequest`](/docs/references/javascript/types/organization-membership-request) objects.
        - Each `OrganizationMembershipRequest` object has an [`accept()`](/docs/references/javascript/types/organization-membership-request#accept) and [`reject()`](/docs/references/javascript/types/organization-membership-request#reject) method to accept or reject the membership request, respectively.
     1. Maps over the `data` array to display the membership requests in a table, providing an "Accept" and "Reject" button for each request that calls the `accept()` and `reject()` methods, respectively.

docs/custom-flows/manage-organization-invitations.mdx

@@ -20,12 +20,12 @@ This guide will demonstrate how to use the Clerk API to build a custom flow for
   <Tab>
     To invite a user:
 
-    1. Use the [`useOrganization()`](/docs/hooks/use-organization) hook to get `organization`, which is the active organization.
+    1. Use the [`useOrganization()`](/docs/hooks/use-organization) hook to get `organization`, which is the [active organization](!active-organization).
     1. Use `organization` to call the [`inviteMember()`](/docs/references/javascript/organization#invite-member) method, with the recipient's email address and desired role passed as arguments.
 
     To revoke an invitation:
 
-    1. Use the `useOrganization()` hook to get `invitations`, which is a list of invitations for the active organization.
+    1. Use the `useOrganization()` hook to get `invitations`, which is a list of invitations for the [active organization](!active-organization).
     1. `invitations` is an array of [`OrganizationInvitation`](/docs/references/javascript/types/organization-invitation) objects. Each `OrganizationInvitation` object has a [`revoke()`](/docs/references/javascript/types/organization-invitation#revoke) method that can be called to revoke the invitation.
 
     The following example includes:
@@ -218,7 +218,7 @@ This guide will demonstrate how to use the Clerk API to build a custom flow for
   <Tab>
     To check if the current user is an organization admin:
 
-    1. Get the active organization's ID from the `clerk` object.
+    1. Get the [active organization's](!active-organization) ID from the `clerk` object.
     1. Call the [`getOrganizationMemberships()`](/docs/references/javascript/user#get-organization-memberships) method to get a list of organizations that the user is a member of. This method returns `data`, which is an array of `OrganizationMembership` objects.
     1. In the list of organizations that the user is a member of, find the `OrganizationMembership` object that has an ID that matches the active organization's ID.
     1. Check the `role` property of the `OrganizationMembership` object to see if the user is an admin.

docs/custom-flows/manage-roles.mdx

@@ -13,7 +13,7 @@ This guide will demonstrate how to use the Clerk API to build a custom flow for
   <Tab>
     The following example:
 
-    1. Uses the [`useOrganization()`](/docs/hooks/use-organization) hook to get `memberships`, which is a list of the active organization's memberships.
+    1. Uses the [`useOrganization()`](/docs/hooks/use-organization) hook to get `memberships`, which is a list of the [active organization's](!active-organization) memberships.
        - `memberships` is an object with `data` that contains an array of [`OrganizationMembership`](/docs/references/javascript/types/organization-membership) objects.
        - Each `OrganizationMembership` object has an [`update()`](/docs/references/javascript/types/organization-membership#update) and [`destroy()`](/docs/references/javascript/types/organization-membership#destroy) method to update the member's role and remove the member from the organization, respectively.
     1. Maps over the `data` array to display the memberships in a table, providing an "Update Role" and "Remove Member" button for each membership that calls the `update()` and `destroy()` methods, respectively.

docs/custom-flows/organization-switcher.mdx

@@ -14,7 +14,7 @@ This guide will demonstrate how to use the Clerk API to build a custom flow for
     The following examples:
 
     1. Use the [`useOrganizationList()`](/docs/hooks/use-organization-list) hook to get `memberships`, which is a list of the current user's organization memberships. `memberships` returns `data`, which is an array of [`OrganizationMembership`](/docs/references/javascript/types/organization-membership) objects.
-    1. Map over the `data` array to display the user's organization memberships in a table, providing a button that calls `setActive()` to set the selected organization as the active organization.
+    1. Map over the `data` array to display the user's organization memberships in a table, providing a button that calls `setActive()` to set the selected organization as the [active organization](!active-organization).
        - If there are no organizations, the [`<CreateOrganization />` component (custom-flow version, not the Clerk component)](/docs/custom-flows/create-organizations) is rendered to allow the user to create an organization.
 
     The difference between the two examples is the parameters passed to the `useOrganizationList()` hook in order to determine how the list is paginated.

docs/custom-flows/update-organizations.mdx

@@ -68,7 +68,7 @@ This guide will demonstrate how to use Clerk's API to build a custom flow for up
   </Tab>
 
   <Tab>
-    The following example uses the `organization.update()` method to update the active organization's name. To see what other attributes can be updated, see the [`update()` reference doc](/docs/references/javascript/organization#update).
+    The following example uses the `organization.update()` method to update the [active organization's](!active-organization) name. To see what other attributes can be updated, see the [`update()` reference doc](/docs/references/javascript/organization#update).
 
     Use the tabs to view the code necessary for the `index.html` and `main.js` files.
 

docs/guides/authorization-checks.mdx

@@ -39,7 +39,7 @@ This guide will show you how to implement authorization checks in order to prote
 
 - When doing authorization checks, it's recommended to use permission-based over role-based, and feature-based over plan-based authorization, as these approaches are more granular, flexible, and more secure.
   - Note: Using `has()` **on the server-side** to check permissions works only with **custom permissions**, as [system permissions](/docs/organizations/roles-permissions#system-permissions) aren't included in the session token claims. To check system permissions, verify the user's role instead.
-- Checking for a role or permission depends on the user having an [active organization](/docs/organizations/overview#active-organization). Without an active organization, the authorization checks will likely always evaluate to false by default.
+- Checking for a role or permission depends on the user having an [active organization](!active-organization). Without an active organization, the authorization checks will likely always evaluate to false by default.
 - If you would like to perform role-based authorization checks **without** using Clerk's organizations feature, see [the Role Based Access Control (RBAC) guide](/docs/references/nextjs/basic-rbac).
 - Permission-based authorization checks link with feature-based authorization checks. This means that if you are checking a custom permission, it will only work if the feature part of the permission key (`org:<feature>:<permission>`) **is a feature included in the organization's active plan**. For example, say you want to check if an organization member has the custom permission `org:teams:manage`, where `teams` is the feature. Before performing the authorization check, you need to ensure that the user's organization is subscribed to a plan that has the `teams` feature. If the user's organization is not subscribed to a plan that has the `teams` feature, the authorization check will always return `false`, even if the user has the custom permission.
 

docs/guides/multi-tenant-architecture.mdx

@@ -55,10 +55,10 @@ B2B SaaS applications with the following characteristics are well-supported with
 Clerk offers a number of building blocks to help integrate organizations into your application:
 
 - The [`<OrganizationSwitcher />` component](/docs/components/organization/organization-switcher) provides a way for your users to select which organization is active. The [`useOrganizationList()` hook](/docs/custom-flows/organization-switcher) can be used for more control.
-- The [`useOrganization()` hook](/docs/hooks/use-organization) can be used to fetch the current, active organization.
+- The [`useOrganization()` hook](/docs/hooks/use-organization) can be used to fetch the current [active organization](!active-organization).
 - The [`<Protect>` component](/docs/components/protect) enables you to limit who can view certain pages based on their role. Additionally, Clerk exposes a number of helper functions, such as [`auth()`](/docs/references/nextjs/auth), and hooks, such as [`useAuth()`](/docs/hooks/use-auth), to check the user's authorization throughout your app and API endpoints.
 
-The organization's ID should be stored in your database alongside each resource so that it can be used to filter and query the resources that should be rendered or returned according to the active organization.
+The organization's ID should be stored in your database alongside each resource so that it can be used to filter and query the resources that should be rendered or returned according to the [active organization](!active-organization).
 
 ## Platforms
 

docs/hooks/use-organization-list.mdx

@@ -4,7 +4,7 @@ description: Access and manage the current user's organization list in your Reac
 sdk: chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start
 ---
 
-The `useOrganizationList()` hook provides access to the current user's organization memberships, invitations, and suggestions. It also includes methods for creating new organizations and managing the active organization.
+The `useOrganizationList()` hook provides access to the current user's organization memberships, invitations, and suggestions. It also includes methods for creating new organizations and managing the [active organization](!active-organization).
 
 ## Parameters
 

docs/hooks/use-organization.mdx

@@ -6,7 +6,7 @@ search:
 sdk: chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start
 ---
 
-The `useOrganization()` hook retrieves attributes of the currently active organization.
+The `useOrganization()` hook retrieves attributes of the currently [active organization](!active-organization).
 
 ## Parameters
 

docs/organizations/org-slugs-in-urls.mdx

@@ -106,7 +106,7 @@ This guide shows you how to add organization slugs to your app's URLs, configure
   ## Configure `clerkMiddleware()` to set the active organization
 
   > [!TIP]
-  > If your app doesn't use `clerkMiddleware()`, or you prefer to manually set the active organization, use the [`setActive()`](/docs/references/javascript/clerk) method to control the active organization on the client side.
+  > If your app doesn't use `clerkMiddleware()`, or you prefer to manually set the [active organization](!active-organization), use the [`setActive()`](/docs/references/javascript/clerk) method to control the active organization on the client side.
 
   With [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware), you can use the [`organizationSyncOptions`](/docs/references/nextjs/clerk-middleware#organization-sync-options) property to declare URL patterns that determine whether a specific organization should be activated.
 

docs/references/astro/auth-store.mdx

@@ -26,21 +26,21 @@ The `$authStore` store provides a convenient way to access the current auth stat
   - `orgId`
   - `string`
 
-  The ID of the user's active organization.
+  The ID of the user's [active organization](!active-organization).
 
   ---
 
   - `orgRole`
   - `string`
 
-  The current user's role in their active organization.
+  The current user's role in their [active organization](!active-organization).
 
   ---
 
   - `orgSlug`
   - `string`
 
-  The URL-friendly identifier of the user's active organization.
+  The URL-friendly identifier of the user's [active organization](!active-organization).
 </Properties>
 
 ## How to use the `$authStore` store

docs/references/astro/locals.mdx

@@ -8,7 +8,7 @@ Through Astro [`locals`](https://docs.astro.build/en/guides/middleware/#storing-
 
 ## `locals.auth()`
 
-`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/backend/types/auth-object){{ target: '_blank' }}.
+`Astro.locals.auth()` returns an `Auth` object. This JavaScript object contains important information like session data, your user's ID, as well as the ID of the [active organization](!active-organization). Learn more about the `Auth` object [here](/docs/references/backend/types/auth-object){{ target: '_blank' }}.
 
 ### `locals.auth()` options
 

docs/references/astro/organization-store.mdx

@@ -8,7 +8,7 @@ The `$organizationStore` store is used to retrieve attributes of the currently a
 
 ## How to use the `$organizationStore` store
 
-The following example demonstrates how to use the `$organizationStore` store to access the [`Organization`](/docs/references/javascript/organization){{ target: '_blank' }} object, which allows you to access the current active organization.
+The following example demonstrates how to use the `$organizationStore` store to access the [`Organization`](/docs/references/javascript/organization){{ target: '_blank' }} object, which allows you to access the current [active organization](!active-organization).
 
 <CodeBlockTabs options={['React', 'Vue', 'Svelte']}>
   ```tsx {{ filename: 'organization.tsx' }}