restructure instance audiences content for better usability

Author: devalog

docs/api-references/audiences

@@ -23,8 +23,6 @@ navigation:
         path: ./pages/navigation/versions.mdx
       - page: Products
         path: ./pages/navigation/products.mdx
-      - page: Instance audiences
-        path: ./pages/navigation/instance-audiences.mdx
       - page: Page-level settings
         path: ./pages/customization/frontmatter.mdx
   - section: Writing content

fern/products/docs/docs.yml

@@ -20,3 +20,12 @@ navigation:
 </CodeBlocks>
 
 Here's [an example from Schematic](https://github.com/SchematicHQ/schematic-fern-config/blob/e19f5ea69a343727ed018e79127bf4fd20ad0f7b/fern/docs.yml#L128-L129) in production.
+
+## Instance audiences
+
+API Reference audiences work alongside [instance audiences](/docs/configuration/products#add-instance-audiences), which control which products and versions appear in each documentation instance. You can use both features together:
+
+- **API Reference audiences** - Control which endpoints and schemas appear within API References
+- **Instance audiences** - Control which products and versions appear in each instance
+
+For example, you might have a `public` API Reference that shows only public endpoints. To ensure this API Reference only appears on your public documentation site, tag the containing product or version with the `public` audience.

fern/products/docs/pages/api-references/audiences.mdx

@@ -119,6 +119,8 @@ An `instance` is the backend of a distinct docs website. Each instance is publis
 instances: 
   - url: plantstore.docs.buildwithfern.com
     custom-domain: docs.plantstore.com
+    audiences:
+      - public
 ```
 
 <ParamField path="instances" type="list of objects" required={false} toc={true}>
@@ -137,6 +139,12 @@ instances:
   If specified, adds an "Edit this page" link to the bottom of each page that links to the given public GitHub repository. Learn more about the [`edit-this-page` configuration](#github-configuration).
 </ParamField>
 
+<ParamField path="instances.audiences" type="list of strings" required={false} toc={true}>
+  Specify which audiences this instance serves (e.g., internal developers, beta testers, public customers). 
+  
+  You can use audiences to control which versions and products appear in each documentation instance, enabling you to create separate sites for different user groups. Content is included when its audience tag matches the instance audience. Content without an audience tag is included by default. Learn more about configuring instance audiences for [products and/or versions](/docs/configuration/products#add-instance-audiences).
+</ParamField>
+
 ## Colors configuration 
 
 ```yaml docs.yml

fern/products/docs/pages/customization/what-is-docs-yml.mdx

@@ -119,7 +119,7 @@ If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure
 </Step>
 </Steps>
 
-### Add versioning to your products (optional)
+### Add versioning to your products
 
 You can optionally add versions to your products. Versioned and unversioned products can live next to each other in your site. 
 
@@ -213,6 +213,58 @@ If your product-specific `.yml` files for **versioned products** includes a `nav
 </Step>
 </Steps>
 
+### Add instance audiences
+
+Control which versions and/or products appear in each [documentation instance](/docs/configuration/what-is-docs-yml#instances-configuration) by tagging them with audiences. This enables separate sites for different user groups (e.g., internal developers, beta testers, public customers).
+
+Content is filtered based on audience tags:
+
+- **Match**: Content with an audience matching the instance audience is included
+- **No match**: Content with a non-matching audience is excluded  
+- **No audience**: Content without an audience tag is included by default
+
+Define audiences for instances, products, and versions in `docs.yml`:
+
+<CodeBlock title="docs.yml">
+```yaml
+instances:
+  - url: internal.docs.buildwithfern.com
+    audiences:
+      - internal # Only shows content tagged with 'internal'
+  - url: public.docs.buildwithfern.com
+    audiences:
+      - public # Only shows content tagged with 'public'
+products:
+  - display-name: Platform API
+    path: ./products/platform-api.yml
+    audiences:
+      - public
+      - internal # This product appears on both instances
+    versions:
+      - display-name: v3
+        path: ./versions/v3.yml
+        audiences:
+          - public # This version only appears on the public instance
+      - display-name: v2 (Internal)
+        path: ./versions/v2.yml
+        audiences:
+          - internal # This version only appears on the internal instance
+  - display-name: Admin Tools
+    path: ./products/admin-tools.yml
+    audiences:
+      - internal # This product only appears on the internal instance
+```
+</CodeBlock>
+
+<Accordion title="Combining with API Reference audiences">
+
+Instance audiences work alongside [API Reference audiences](/docs/api-references/audiences), which filter endpoints and schemas within your API documentation. You can use both features together:
+
+- **Instance audiences** - Control which products and versions appear in each instance
+- **API Reference audiences** - Control which endpoints and schemas appear within API References
+
+For example, you might have a `public` instance that includes only public products. Within those products, the API Reference should be marked as `public` so it is filtered to show only `public` endpoints.
+</Accordion>
 
 ## Customize selector styling
 

fern/products/docs/pages/navigation/instance-audiences.mdx

@@ -40,7 +40,7 @@ Version-specific `yml` files:
 
 <Markdown src="/snippets/version-specific-yml-files.mdx" />
 
-<Note>You can also have multiple products, some versioned and some unversioned. For more information on setting up multiple products, follow our [product switching docs](/docs/configuration/products).</Note>
+<Note>You can also have [multiple products, some versioned and some unversioned](/docs/configuration/products).</Note>
 </Step>
 <Step title="Add your version configuration">
 
@@ -79,6 +79,41 @@ versions:
 <Step title="Remove extra navigation from docs.yml">
 
 If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the version-specific `.yml` files. 
+</Step>
+<Step title="Add instance audiences">
+
+Control which versions appear in each [documentation instance](/docs/configuration/what-is-docs-yml#instances-configuration) by tagging them with audiences. This enables separate sites for different user groups (e.g., internal developers, beta testers, public customers).
+
+Content is filtered based on audience tags:
+
+- **Match**: Content with an audience matching the instance audience is included
+- **No match**: Content with a non-matching audience is excluded  
+- **No audience**: Content without an audience tag is included by default
+
+Define audiences for instances and versions in `docs.yml`:
+
+<CodeBlock title="docs.yml">
+
+```yaml maxLines=10
+instances:
+  - url: internal.docs.buildwithfern.com
+    audiences:
+      - internal # Only shows content tagged with 'internal'
+  - url: public.docs.buildwithfern.com
+    audiences:
+      - public # Only shows content tagged with 'public'
+versions:
+  - display-name: v3
+    path: ./versions/v3.yml
+    audiences:
+      - public # This version only appears on the public instance
+  - display-name: v2 (Internal)
+    path: ./versions/v2.yml
+    audiences:
+      - internal # This version only appears on the internal instance
+```
+</CodeBlock>
+
 </Step>
 </Steps>