fix(docs): move audiences docs into own page (#4389)

fern/docs.yml

@@ -64,6 +64,9 @@ navigation:
               - page: Parameter Names
                 path: ./pages/api-definition/openapi/extensions/parameter-names.mdx
                 slug: parameter-names
+              - page: Audiences
+                path: ./pages/api-definition/openapi/extensions/audiences.mdx
+                slug: audiences              
               - page: Other
                 path: ./pages/api-definition/openapi/extensions/others.mdx
                 slug: others              

fern/pages/api-definition/openapi/extensions/audiences.mdx

@@ -0,0 +1,104 @@
+---
+title: Audiences
+subtitle: Use `x-fern-audiences` to filter to relevant endpoints, schemas and properties
+---
+
+Audiences are a useful tool for segmenting your API for different consumers. Common examples of audiences include `public` 
+and `beta`. 
+
+<Info>
+  Remember to filter your SDKs and Docs after specifying audiences. If **no audiences** are specified, 
+  nothing will be filtered.
+
+<AccordionGroup>
+
+<Accordion title="SDKs">
+The following example configures the SDK to filter to the `public` audience:
+
+```yaml title="generators.yml" {3-4}
+groups:
+  sdks:
+    audiences:
+      - public
+    generators:
+      - name: fernapi/fern-tyepscript-node-sdk
+        version: 0.8.8
+```
+</Accordion>
+
+<Accordion title="Docs">
+The following example configures the docs to filter to the `public` audience:
+
+```yaml title="docs.yml" {3-4}
+navigation:
+  - api: API Reference
+    audiences:
+      - public
+```
+</Accordion>
+
+</AccordionGroup>
+
+</Info>
+
+## Audiences for Endpoints
+
+To mark an endpoint with a particular audience, add the `x-fern-audiences` extension to the relevant endpoint.
+
+In the example below, the `POST /users/sendEmail` endpoint is only available to public consumers:
+
+```yaml title="openapi.yml" {4-5}
+paths:
+  /users/sendEmail:
+    post:
+      x-fern-audiences:
+        - public
+      operationId: send_email
+```
+
+## Audiences for Schemas
+
+Schemas can be marked for different audiences, as well.
+
+In this example, the `Email` type is available to both public and beta customers.
+
+```yaml title="openapi.yml" {13-15}
+components:
+  schemas:
+    Email:
+      title: Email
+      type: object
+      properties:
+        subject:
+          type: string
+        body:
+          type: string
+        to:
+          type: string
+      x-fern-audiences:
+        - public
+        - beta
+```
+
+## Audiences for Properties
+
+Properties can be marked for different audiences, as well.
+
+In this example, the `to` property is available to beta customers only.
+
+```yaml title="openapi.yml" {13-17}
+components:
+  schemas:
+    Email:
+      title: Email
+      type: object
+      properties:
+        subject:
+          type: string
+        body:
+          type: string
+        to:
+          type: string
+          x-fern-audiences:
+            - beta
+```

fern/pages/api-definition/openapi/extensions/others.mdx

@@ -310,91 +310,6 @@ paths:
   /users: ...
 ```
 
-## Audiences
-
-Audiences are a useful tool for segmenting your API for different consumers. You can configure your Fern Docs to publish documentation specific to an `Audience`. You can use [audiences in your Fern Definition](/learn/api-definition/fern/audiences), too.
-
-Common examples of audiences include:
-
-- Internal consumers (e.g., frontend developers who use the API)
-- Beta testers
-- Customers
-
-By default, if no audience is specified, it will be accessible to all consumers.
-
-### Audiences for Endpoints
-
-To mark an endpoint with a particular audience, add the `x-fern-audiences` extension to the relevant endpoint.
-
-In the example below, the `POST /users/sendEmail` endpoint is only available to internal consumers:
-
-```yaml title="openapi.yml" {4-5}
-paths:
-  /users/sendEmail:
-    post:
-      x-fern-audiences:
-        - internal
-      operationId: send_email
-      ...
-```
-
-### Audiences for Components
-
-Components can be marked for different audiences, as well.
-
-In this example, the `Email` type is available to both internal and beta customers, while the `to` property is available to beta customers only:
-
-```yaml title="openapi.yml" {13-17}
-components:
-  schemas:
-    Email:
-      title: Email
-      type: object
-      properties:
-        subject:
-          type: string
-        body:
-          type: string
-        to:
-          type: string
-          x-fern-audiences: <-- property audience
-            - beta
-      x-fern-audiences: <-- type audience
-        - internal
-        - beta
-```
-
-### Audiences for SDKs
-
-In `generators.yml`, you can apply audience filters so that only certain
-endpoints are passed to the generators.
-
-The following example configures the SDKs to filter for the `customers` audience:
-
-```yaml title="generators.yml" {3-4}
-groups:
-  sdks:
-    audiences:
-      - customers
-    generators:
-      - name: fernapi/fern-tyepscript-node-sdk
-        version: 0.8.8
-        ...
-```
-
-### Audiences for Docs
-
-If generating Fern Docs, update your `docs.yml` configuration to include your audiences.
-
-The following example shows how to configure your `docs.yml` to publish documentation for the `customers` audience:
-
-```yaml title="docs.yml" {3-4}
-navigation:
-  - api: API Reference
-    audiences:
-      - customers
-```
-
 ## Streaming
 
 The `x-fern-streaming` extension is used to specify that an endpoint's response is streamed.