Skip to content

Document instance audiences feature #1471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 27, 2025
Merged

Document instance audiences feature #1471

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
96c79d0
Document instance audiences feature
devin-ai-integration[bot] Oct 27, 2025
859188d
Fix Vale style errors in instance audiences documentation
devin-ai-integration[bot] Oct 27, 2025
60c67a1
Update instance-audiences.mdx
chdeskur Oct 27, 2025
41b5f57
restructure instance audiences content for better usability
devalog Oct 27, 2025
c3244d8
delete empty file
devalog Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions fern/products/docs/pages/api-references/audiences.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
8 changes: 8 additions & 0 deletions fern/products/docs/pages/customization/what-is-docs-yml.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,8 @@
instances:
- url: plantstore.docs.buildwithfern.com
custom-domain: docs.plantstore.com
audiences:
- public
```

<ParamField path="instances" type="list of objects" required={false} toc={true}>
Expand All @@ -137,6 +139,12 @@
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).

Check failure on line 143 in fern/products/docs/pages/customization/what-is-docs-yml.mdx

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Foreign] Use 'for example' instead of 'e.g.,'.

Raw Output:
{"message": "[Microsoft.Foreign] Use 'for example' instead of 'e.g.,'.", "location": {"path": "fern/products/docs/pages/customization/what-is-docs-yml.mdx", "range": {"start": {"line": 143, "column": 49}}}, "severity": "ERROR"}

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
Expand Down
54 changes: 53 additions & 1 deletion fern/products/docs/pages/navigation/products.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@
</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.

Expand Down Expand Up @@ -213,6 +213,58 @@
</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).

Check failure on line 218 in fern/products/docs/pages/navigation/products.mdx

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Foreign] Use 'for example' instead of 'e.g.,'.

Raw Output:
{"message": "[Microsoft.Foreign] Use 'for example' instead of 'e.g.,'.", "location": {"path": "fern/products/docs/pages/navigation/products.mdx", "range": {"start": {"line": 218, "column": 229}}}, "severity": "ERROR"}

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.

Check failure on line 266 in fern/products/docs/pages/navigation/products.mdx

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'it's' instead of 'it is'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'it's' instead of 'it is'.", "location": {"path": "fern/products/docs/pages/navigation/products.mdx", "range": {"start": {"line": 266, "column": 158}}}, "severity": "ERROR"}
</Accordion>

## Customize selector styling

Expand Down
37 changes: 36 additions & 1 deletion fern/products/docs/pages/navigation/versions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@

<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">

Expand Down Expand Up @@ -79,6 +79,41 @@
<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).

Check failure on line 85 in fern/products/docs/pages/navigation/versions.mdx

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Foreign] Use 'for example' instead of 'e.g.,'.

Raw Output:
{"message": "[Microsoft.Foreign] Use 'for example' instead of 'e.g.,'.", "location": {"path": "fern/products/docs/pages/navigation/versions.mdx", "range": {"start": {"line": 85, "column": 213}}}, "severity": "ERROR"}

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>

Expand Down