Skip to content

Commit 96c79d0

Browse files
devin-ai-integration[bot]chdeskur
devin-ai-integration[bot]
and
chdeskur
committed
Document instance audiences feature
Add comprehensive documentation for the new instance audiences feature that allows filtering versions and products by audience to control what gets generated in each docs instance. - Created new page at fern/products/docs/pages/navigation/instance-audiences.mdx - Added page to Configuration section in docs.yml navigation - Includes examples for configuring audiences on instances, versions, and products - Explains filtering logic and how to publish to specific instances - Shows how instance audiences work alongside API reference audiences Co-Authored-By: Catherine Deskur <[email protected]>
1 parent d3cc43e commit 96c79d0

File tree

2 files changed

+170
-0
lines changed

2 files changed

+170
-0
lines changed

‎fern/products/docs/docs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ navigation:
2323
path: ./pages/navigation/versions.mdx
2424
- page: Products
2525
path: ./pages/navigation/products.mdx
26+
- page: Instance audiences
27+
path: ./pages/navigation/instance-audiences.mdx
2628
- page: Page-level settings
2729
path: ./pages/customization/frontmatter.mdx
2830
- section: Writing content

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

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
title: Instance audiences
3+
subtitle: Filter versions and products by audience to control what gets generated in each docs instance.
4+
---
5+
6+
<Markdown src="/snippets/pro-plan.mdx"/>
7+
8+
Instance audiences allow you to control which versions and products are included in each documentation instance. This is useful for creating separate documentation sites for different audiences, such as internal developers, beta testers, or public customers.
9+
10+
## How it works
11+
12+
You can add audiences to three levels in your `docs.yml` configuration:
13+
14+
1. **Instances** - Define which audience(s) an instance serves
15+
2. **Versions** - Tag versions with audience(s) they belong to
16+
3. **Products** - Tag products with audience(s) they belong to
17+
18+
When you add an audience to a product or version and it matches the audience of the instance, that content will be included. If the audience is defined but does not match the instance audience, it will be excluded. If no audience is defined, all content will be included by default.
19+
20+
## Configuration
21+
22+
### Add audiences to instances
23+
24+
Define which audience(s) an instance serves by adding the `audiences` property to an instance in your `docs.yml`:
25+
26+
<CodeBlock title="docs.yml">
27+
```yaml {3-4}
28+
instances:
29+
- url: plantstore.docs.buildwithfern.com
30+
audiences:
31+
- public
32+
- url: internal.plantstore.docs.buildwithfern.com
33+
audiences:
34+
- internal
35+
```
36+
</CodeBlock>
37+
38+
### Add audiences to versions
39+
40+
Tag versions with audiences to control which instances include them:
41+
42+
<CodeBlock title="docs.yml">
43+
```yaml {4-5, 8-9}
44+
versions:
45+
- display-name: Latest
46+
path: ./versions/latest.yml
47+
audiences:
48+
- public
49+
- display-name: Beta
50+
path: ./versions/beta.yml
51+
audiences:
52+
- internal
53+
- beta
54+
```
55+
</CodeBlock>
56+
57+
### Add audiences to products
58+
59+
Tag products with audiences to control which instances include them:
60+
61+
<CodeBlock title="docs.yml">
62+
```yaml {4-5, 9-10}
63+
products:
64+
- display-name: Public API
65+
path: ./products/public-api.yml
66+
audiences:
67+
- public
68+
slug: public-api
69+
- display-name: Internal Tools
70+
path: ./products/internal-tools.yml
71+
audiences:
72+
- internal
73+
slug: internal-tools
74+
```
75+
</CodeBlock>
76+
77+
## Filtering logic
78+
79+
The filtering logic works as follows:
80+
81+
- **Match**: If a version or product has an audience defined that matches the instance audience, it will be included
82+
- **No match**: If a version or product has an audience defined that does not match the instance audience, it will be excluded
83+
- **No audience defined**: If no audience is defined on a version or product, it will be included in all instances
84+
85+
## Example configuration
86+
87+
Here's a complete example showing how to use instance audiences to create separate documentation sites for public and internal users:
88+
89+
<CodeBlock title="docs.yml">
90+
```yaml
91+
instances:
92+
- url: docs.plantstore.com
93+
custom-domain: docs.plantstore.com
94+
audiences:
95+
- public
96+
- url: internal.plantstore.docs.buildwithfern.com
97+
audiences:
98+
- internal
99+
100+
products:
101+
- display-name: Plant API
102+
path: ./products/plant-api.yml
103+
audiences:
104+
- public
105+
slug: plant-api
106+
subtitle: Public API for managing plants
107+
108+
- display-name: Admin API
109+
path: ./products/admin-api.yml
110+
audiences:
111+
- internal
112+
slug: admin-api
113+
subtitle: Internal API for admin operations
114+
115+
- display-name: Getting Started
116+
path: ./products/getting-started.yml
117+
slug: getting-started
118+
subtitle: Introduction to Plant Store
119+
# No audience defined - included in all instances
120+
121+
versions:
122+
- display-name: v3
123+
path: ./versions/v3.yml
124+
audiences:
125+
- public
126+
- display-name: v2
127+
path: ./versions/v2.yml
128+
audiences:
129+
- public
130+
- display-name: v1 (Internal Only)
131+
path: ./versions/v1.yml
132+
audiences:
133+
- internal
134+
```
135+
</CodeBlock>
136+
137+
In this example:
138+
139+
- The public instance at `docs.plantstore.com` will include:
140+
- Plant API product (matches `public` audience)
141+
- Getting Started product (no audience defined)
142+
- v3 and v2 versions (match `public` audience)
143+
144+
- The internal instance at `internal.plantstore.docs.buildwithfern.com` will include:
145+
- Admin API product (matches `internal` audience)
146+
- Getting Started product (no audience defined)
147+
- v1 version (matches `internal` audience)
148+
149+
## Publishing to specific instances
150+
151+
When publishing your documentation, use the `--instance` flag to specify which instance to publish:
152+
153+
```bash
154+
# Publish to the public instance
155+
fern docs publish --instance docs.plantstore.com
156+
157+
# Publish to the internal instance
158+
fern docs publish --instance internal.plantstore.docs.buildwithfern.com
159+
```
160+
161+
## Combining with API reference audiences
162+
163+
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:
164+
165+
- **Instance audiences** - Control which products and versions appear in each instance
166+
- **API reference audiences** - Control which endpoints and schemas appear within API references
167+
168+
For example, you might have a public instance that includes only public products, and within those products, the API references are further filtered to show only public endpoints.

0 commit comments

Comments
 (0)