clean up /javascript/clerk (#371)

docs/references/javascript/clerk/create-organization.mdx

@@ -7,11 +7,11 @@ description: The `<CreateOrganization />` component is used to render an organiz
 
 <Images alt="Create Organization Example" width={992} height={568} src="/docs/images/ui-components/component-org_create.svg" />
 
-The `<CreateOrganization />` component is used to render an organization creation UI that allows users to create brand new organizations within your application.
+The [`<CreateOrganization />`][createorg-ref] component is used to render an organization creation UI that allows users to create brand new organizations within your application.
 
 ## `mountCreateOrganization()`
 
-Render the `<CreateOrganization />` component to an HTML `<div>` element.
+Render the [`<CreateOrganization />`][createorg-ref] component to an HTML `<div>` element.
 
 ### Usage
 
@@ -70,12 +70,12 @@ function mountCreateOrganization(node: HTMLDivElement, props?: CreateOrganizatio
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The `<div>` element used to render in the `<CreateOrganization />` component |
-| `props?` | [`CreateOrganizationProps`](#create-organization-props) | The properties to pass to the `<CreateOrganization />` component |
+| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The `<div>` element used to render in the [`<CreateOrganization />`][createorg-ref] component |
+| `props?` | [`CreateOrganizationProps`](#create-organization-props) | The properties to pass to the [`<CreateOrganization />`][createorg-ref] component |
 
 ## `unmountCreateOrganization`
 
-Unmount and run cleanup on an existing `<CreateOrganization />` component instance.
+Unmount and run cleanup on an existing [`<CreateOrganization />`][createorg-ref] component instance.
 
 ### Usage
 
@@ -134,11 +134,11 @@ function unmountCreateOrganization(node: HTMLDivElement): void;
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The container `<div>` element with a rendered `<CreateOrganization />` component instance |
+| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The container `<div>` element with a rendered [`<CreateOrganization />`][createorg-ref] component instance |
 
 ## `openCreateOrganization`
 
-Opens the `<CreateOrganization />` component as an overlay at the root of your HTML `body` element.
+Opens the [`<CreateOrganization />`][createorg-ref] component as an overlay at the root of your HTML `body` element.
 
 ### Usage
 
@@ -186,7 +186,7 @@ function openCreateOrganization(props?: CreateOrganizationProps): void;
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `props?` | [`CreateOrganizationProps`](#create-organization-props) | The properties to pass to the `<CreateOrganization />` component |
+| `props?` | [`CreateOrganizationProps`](#create-organization-props) | The properties to pass to the [`<CreateOrganization />`][createorg-ref] component |
 
 ## `closeCreateOrganization`
 
@@ -243,6 +243,10 @@ All props below are optional.
 | Name | Type | Description |
 | --- | --- | --- |
 | `afterCreateOrganizationUrl` | `string` | Full URL or path to navigate after creating a new organization. |
-| `path` | `string` | The path where the component is mounted when path-based routing is used. -e.g. /create-org.<br />This prop is ignored in hash and virtual based routing. |
-| `routing` | `string` | The routing strategy for your pages. <br />Supported values are: <ul><li>`hash` (default): Hash-based routing.</li> <li>`path`: Path-based routing.</li> <li>`virtual`: Virtual-based routing.</li></ul> |
-| `appearance` | `object` | Control the look and feel of the component. |
+| `routing` | `'hash' \| 'path' \| 'virtual'` | The routing strategy for your pages. <br />Supported values are: <ul><li>`hash` (default): Hash-based routing.</li> <li>`path`: Path-based routing.</li> <li>`virtual`: Virtual-based routing.</li></ul> |
+| `path` | `string` | The path where the component is mounted when path-based routing is used. -e.g. /create-org. This prop is ignored in hash and virtual based routing. |
+| `appearance` | <code>[Appearance](/docs/components/customization/overview) \| undefined</code> | Optional object to style your components. Will only affect [Clerk Components][components-ref] and not [Account Portal][ap-ref] pages. |
+
+[components-ref]: /docs/components/overview
+[ap-ref]: /docs/account-portal/overview
+[createorg-ref]: /docs/components/organization/create-organization]

docs/references/javascript/clerk/organization-profile.mdx

@@ -7,11 +7,11 @@ description: The <OrganizationProfile /> component is used to render a beautiful
 
 <Images alt="Organization Profile Example" width={1024} height={548} src="/docs/images/ui-components/component-org_profile.svg" />
 
-The `<OrganizationProfile />` component is used to render a beautiful, full-featured organization management UI that allows users to manage their organization profile and security settings.
+The [`<OrganizationProfile />`][orgprofile-ref] component is used to render a beautiful, full-featured organization management UI that allows users to manage their organization profile and security settings.
 
 ## `mountOrganizationProfile()`
 
-Render the `<OrganizationProfile />` component to an HTML `<div>` element.
+Render the [`<OrganizationProfile />`][orgprofile-ref] component to an HTML `<div>` element.
 
 ### Usage
 
@@ -70,12 +70,12 @@ function mountOrganizationProfile(node: HTMLDivElement, props?: OrganizationProf
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The `<div>` element used to render in the `<OrganizationProfile />` component |
-| `props?` | [`OrganizationProfileProps`](#organization-profile-props) | The properties to pass to the `<OrganizationProfile />` component |
+| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The `<div>` element used to render in the [`<OrganizationProfile />`][orgprofile-ref] component |
+| `props?` | [`OrganizationProfileProps`](#organization-profile-props) | The properties to pass to the [`<OrganizationProfile />`][orgprofile-ref] component |
 
 ## `unmountOrganizationProfile()`
 
-Unmount and run cleanup on an existing `<OrganizationProfile />` component instance.
+Unmount and run cleanup on an existing [`<OrganizationProfile />`][orgprofile-ref] component instance.
 
 ### Usage
 
@@ -134,11 +134,11 @@ function unmountOrganizationProfile(node: HTMLDivElement): void;
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The container `<div>` element with a rendered `<OrganizationProfile />` component instance. |
+| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The container `<div>` element with a rendered [`<OrganizationProfile />`][orgprofile-ref] component instance. |
 
 ## `openOrganizationProfile()`
 
-Opens the `<OrganizationProfile />` component as an overlay at the root of your HTML `body` element.
+Opens the [`<OrganizationProfile />`][orgprofile-ref] component as an overlay at the root of your HTML `body` element.
 
 ### Usage
 
@@ -186,7 +186,7 @@ function openOrganizationProfile(props?: OrganizationProfileProps): void;
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `props?` | [`OrganizationProfileProps`](#organization-profile-props) | The properties to pass to the `<OrganizationProfile />` component |
+| `props?` | [`OrganizationProfileProps`](#organization-profile-props) | The properties to pass to the [`<OrganizationProfile />`][orgprofile-ref] component |
 
 ## `closeOrganizationProfile()`
 
@@ -243,6 +243,10 @@ All props below are optional.
 | Name | Type | Description |
 | --- | --- | --- |
 | `afterLeaveOrganizationUrl` | `string` | Full URL or path to navigate after leaving an organization. |
-| `path` | `string` | The path where the component is mounted when path-based routing is used. -e.g. /org-profile.<br />This prop is ignored in hash and virtual based routing. |
-| `routing` | `string` | The routing strategy for your pages. <br />Supported values are: <ul><li>`hash` (default): Hash based routing.</li> <li>`path`: Path based routing.</li> <li>`virtual`: Virtual based routing.</li></ul> |
-| `appearance` | `object` | Control the look and feel of the component. |
+| `routing` | `'hash' \| 'path' \| 'virtual'` | The routing strategy for your pages. <br />Supported values are: <ul><li>`hash` (default): Hash-based routing.</li> <li>`path`: Path-based routing.</li> <li>`virtual`: Virtual-based routing.</li></ul> |
+| `path` | `string` | The path where the component is mounted when path-based routing is used.<br/>e.g. `/user-profile`.<br />This prop is ignored in hash-based routing. |
+| `appearance` | <code>[Appearance](/docs/components/customization/overview) \| undefined</code> | Optional object to style your components. Will only affect [Clerk Components][components-ref] and not [Account Portal][ap-ref] pages. |
+
+[orgprofile-ref]: /docs/components/organization/organization-profile
+[components-ref]: /docs/components/overview
+[ap-ref]: /docs/account-portal/overview

docs/references/javascript/clerk/organization-switcher.mdx

@@ -7,11 +7,11 @@ description: The <OrganizationSwitcher /> component is used to enable the abilit
 
 <Images alt="Organization Switcher Example" width={992} height={568} src="/docs/images/ui-components/component-org_switcher.svg" />
 
-The `<OrganizationSwitcher />` component is used to enable the ability to switch between available organizations the user may be part of in your application.
+The [`<OrganizationSwitcher />`][orgswitcher-ref] component is used to enable the ability to switch between available organizations the user may be part of in your application.
 
 ## `mountOrganizationSwitcher()`
 
-Render the `<OrganizationSwitcher />` component to an HTML `<div>` element.
+Render the [`<OrganizationSwitcher />`][orgswitcher-ref] component to an HTML `<div>` element.
 
 ### Usage
 
@@ -70,12 +70,12 @@ function mountOrganizationSwitcher(node: HTMLDivElement, props?: OrganizationSwi
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The `<div>` element used to render in the `<OrganizationSwitcher />` component |
-| `props?` | [`OrganizationSwitcherProps`](#organization-switcher-props) | The properties to pass to the `<OrganizationSwitcher />` component |
+| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The `<div>` element used to render in the [`<OrganizationSwitcher />`][orgswitcher-ref] component |
+| `props?` | [`OrganizationSwitcherProps`](#organization-switcher-props) | The properties to pass to the [`<OrganizationSwitcher />`][orgswitcher-ref] component |
 
 ## `unmountOrganizationSwitcher()`
 
-Unmount and run cleanup on an existing `<OrganizationSwitcher />` component instance.
+Unmount and run cleanup on an existing [`<OrganizationSwitcher />`][orgswitcher-ref] component instance.
 
 ### Usage
 
@@ -134,7 +134,7 @@ function unmountOrganizationSwitcher(node: HTMLDivElement): void;
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The container `<div>` element with a rendered `<OrganizationSwitcher />` component instance |
+| `node` | [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) | The container `<div>` element with a rendered [`<OrganizationSwitcher />`][orgswitcher-ref] component instance |
 
 ## `OrganizationSwitcherProps`
 
@@ -143,12 +143,18 @@ All props below are optional.
 | Name | Type | Description |
 | --- | --- | --- |
 | `afterCreateOrganizationUrl` | `string` | Full URL or path to navigate after creating a new organization. |
-| `appearance` | `object` | Control the look and feel of the component. |
-| `createOrganizationUrl` | `string` | Full URL or path where the `<CreateOrganization />`component is mounted. |
-| `organizationProfileUrl` | `string` | Full URL or path where the `<OrganizationProfile />` component is mounted. |
-| `createOrganizationMode` | `'modal' \| 'navigation'` | Controls whether clicking the **Create organization** button will cause the `<CreateOrganization />` component to open as a modal, or if the browser will navigate to the `createOrganizationUrl` where `<CreateOrganization />` is mounted as a page. <br />Defaults to: `'modal'` |
-| `organizationProfileMode` | `'modal' \| 'navigation'` | Controls whether clicking the **Manage organization** button will cause the `<OrganizationProfile />` component to open as a modal, or if the browser will navigate to the `organizationProfileUrl` where `<OrganizationProfile />` is mounted as a page. <br />Defaults to: `'modal'` |
+| `appearance` | <code>[Appearance](/docs/components/customization/overview) \| undefined</code> | Optional object to style your components. Will only affect [Clerk Components][components-ref] and not [Account Portal][ap-ref] pages. |
+| `createOrganizationUrl` | `string` | Full URL or path where the [`<CreateOrganization />`][createorg-ref]component is mounted. |
+| `organizationProfileUrl` | `string` | Full URL or path where the [`<OrganizationProfile />`][orgprofile-ref] component is mounted. |
+| `createOrganizationMode` | `'modal' \| 'navigation'` | Controls whether clicking the **Create organization** button will cause the [`<CreateOrganization />`][createorg-ref] component to open as a modal, or if the browser will navigate to the `createOrganizationUrl` where [`<CreateOrganization />`][createorg-ref] is mounted as a page. <br />Defaults to: `'modal'` |
+| `organizationProfileMode` | `'modal' \| 'navigation'` | Controls whether clicking the **Manage organization** button will cause the [`<OrganizationProfile />`][orgprofile-ref] component to open as a modal, or if the browser will navigate to the `organizationProfileUrl` where [`<OrganizationProfile />`][orgprofile-ref] is mounted as a page. <br />Defaults to: `'modal'` |
 | `afterLeaveOrganizationUrl` | `string` | Full URL or path to navigate to after the user leaves the currently active organization. |
 | `afterSwitchOrganizationUrl` | `string` | Full URL or path to navigate after a successful organization switch. |
-| `hidePersonal` | `boolean` | By default, users can switch between organization and their personal account. This option controls whether `<OrganizationSwitcher />` will include the user's personal account in the organization list. Setting this to `false` will hide the personal account entry, and users will only be able to switch between organizations. <br />Defaults to: `true` |
-| `defaultOpen` | `boolean` | Controls the default state of the `<OrganizationSwitcher />` component. |
+| `hidePersonal` | `boolean` | By default, users can switch between organization and their personal account. This option controls whether [`<OrganizationSwitcher />`][orgswitcher-ref] will include the user's personal account in the organization list. Setting this to `false` will hide the personal account entry, and users will only be able to switch between organizations. <br />Defaults to: `true` |
+| `defaultOpen` | `boolean` | Controls the default state of the [`<OrganizationSwitcher />`][orgswitcher-ref] component. |
+
+[components-ref]: /docs/components/overview
+[ap-ref]: /docs/account-portal/overview
+[orgswitcher-ref]: /docs/components/organization/organization-switcher
+[createorg-ref]: /docs/components/organization/create-organization
+[orgprofile-ref]: /docs/components/organization/organization-profile

docs/references/javascript/clerk/session-methods.mdx

@@ -16,22 +16,22 @@ function setSession(
 ): Promise<void>;
 ```
 
-Set the current session on this client to the provided session. The provided session can be either a complete <a href="/docs/references/javascript/session">Session</a> object or simply its unique identifier.
+Set the current session on this client to the provided session. The provided session can be either a complete [`Session`][session-ref] object or simply its unique identifier.
 
 Passing null as the session will result in the current session to be removed from the client.
 
 If an active session already exists, it will be replaced with the new one. The change happens in three steps:
 
-1. The current <a href="/docs/references/javascript/session">`Session`</a> object is set to `undefined`, which causes the control components to stop rendering their children as though Clerk is still initializing.
+1. The current [`Session`][session-ref] object is set to `undefined`, which causes the control components to stop rendering their children as though Clerk is still initializing.
 2. The `beforeEmit` callback is executed. If a `Promise` is returned, Clerk waits for the `Promise` to resolve.
-3. The current <a href="/docs/references/javascript/session">`Session`</a> is set to the passed `session`. This causes the control components to render their children again.
+3. The current [`Session`][session-ref] is set to the passed `session`. This causes the control components to render their children again.
 
 ### Props
 
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `session` | [`Session`](/docs/references/javascript/session) \| `string` \| `null` | A `Session` object or `Session ID` string to be set as the current session, or `null` to simply remove the active session, without setting a new one. |
+| `session` | [`Session`][session-ref] \| `string` \| `null` | A `Session` object or `Session ID` string to be set as the current session, or `null` to simply remove the active session, without setting a new one. |
 | `beforeEmit?` | `(session: Session \| null) => Promise<any>` | Callback that will trigger when the current session is set to `undefined`, before finally being set to the passed session. Usually used for navigation. |
 
 ### Returns
@@ -58,7 +58,7 @@ An experimental method used to set the active session and/or organization.
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `session` | `Session \| string \| null` | The session resource or session ID (string version) to be set as active. If `null`, the current session is deleted. |
+| `session` | [`Session`][session-ref] \| `string` \| `null` | The session resource or session ID (string version) to be set as active. If `null`, the current session is deleted. |
 | `organization` | [`Organization`](/docs/references/javascript/organization/organization) \| `string` \| `null` | The organization resource or organization ID (string version) to be set as active in the current session. If `null`, the currently active organization is removed as active. |
 | `beforeEmit?` | `(session?: Session \| null) => void \| Promise<any>` | Callback run just before the active session and/or organization is set to the passed object. Can be used to hook up for pre-navigation actions. |
 
@@ -67,3 +67,5 @@ An experimental method used to set the active session and/or organization.
 | Type | Description |
 | --- | --- |
 | `Promise<void>` | The `Promise` will resolve after the passed `session` or `organization` is set. |
+
+[session-ref]: /docs/references/javascript/session