From d510777a94e8d2f4c162f004fd28d184e2d3cbd1 Mon Sep 17 00:00:00 2001 From: Justin Torre Date: Tue, 15 Sep 2026 23:52:01 -0700 Subject: [PATCH 1/3] Document audiences Adds a page for tagging pages and navigation groups with an audience so each kind of reader is shown the content written for them, with the reserved default audience, how readers land in an audience from their groups, how the property combines with groups and public, and a worked example. Cross-links from the authentication, personalization, and navigation pages. Co-Authored-By: Claude Fable 5.1 --- create/audiences.mdx | 173 ++++++++++++++++++++++++++++++++ create/personalization.mdx | 2 + deploy/authentication-setup.mdx | 2 + docs.json | 1 + organize/navigation.mdx | 2 +- 5 files changed, 179 insertions(+), 1 deletion(-) create mode 100644 create/audiences.mdx diff --git a/create/audiences.mdx b/create/audiences.mdx new file mode 100644 index 0000000000..0ea24f850c --- /dev/null +++ b/create/audiences.mdx @@ -0,0 +1,173 @@ +--- +title: "Audiences" +description: "Show each group of readers the content written for them by tagging pages and navigation groups with an audience." +keywords: ["audience", "audiences", "internal documentation", "groups", "personalization", "hide pages"] +--- + + + Audiences require [OAuth or JWT authentication](/deploy/authentication-setup), or [personalization](/create/personalization) with JWT or OAuth, on an [Enterprise plan](https://mintlify.com/pricing?ref=audiences). + + +Audiences let you serve more than one kind of reader from a single site. Tag a page or a navigation group with an audience, and only readers in that audience see it in navigation, search, the assistant, and the MCP server. Everyone else sees the site as if the content were not there. + +An audience is named by a group. A reader whose user data includes the group `internal` is in the `internal` audience. There is nothing to declare ahead of time: the group names your identity provider already sends are the audience names you use in your content. + + + Audiences control what a reader is shown. They do not control what a reader can access. A page tagged with an audience is still reachable at its URL by anyone who can otherwise open it. To restrict access, use [groups](/deploy/authentication-setup#control-access-with-groups). + + +## Tag content with an audience + +Add `audience` to a navigation group in `docs.json` or to a page's frontmatter. The value is a group name or a list of group names. + +### Navigation groups + +Every page in the group inherits the audience unless it sets its own. + +```json Navigation groups with audiences highlight={6,11} +{ + "navigation": { + "groups": [ + { + "group": "Feature flags", + "audience": "default", + "pages": ["platform/feature-flags", "platform/rollouts"] + }, + { + "group": "Feature flags", + "audience": "internal", + "pages": ["internal/feature-flags", "internal/legacy-config"] + } + ] + } +} +``` + +Two groups can share a name. A reader in the `internal` audience sees the second group and never the first. Every other reader sees the first group and never the second. The sidebar looks the same to both; the pages behind it differ. + +### Pages + +Set `audience` in frontmatter to tag a single page or to override the audience of its group. + +```mdx Page with an audience highlight={3} +--- +title: "Unreleased features" +audience: ["internal", "beta"] +--- +``` + +A page with more than one audience is shown to readers in any of them. + +### Shared content + +Content without an `audience` is shown to every reader. Keep quickstarts, authentication guides, and anything else both audiences need untagged, and it appears once, in every reader's view. + +## The default audience + +`default` is a reserved audience name for readers who belong to none of the audiences your site uses. Every visitor who is not signed in is in the default audience, and so is a signed-in reader whose groups do not match any audience tag on your site. + +Tag content with `default` to show it only to those readers. This is how you keep a public page out of the view of readers who have their own version of it. + +```json Public content that internal readers should not see highlight={3} +{ + "group": "Billing", + "audience": "default", + "pages": ["platform/billing", "platform/support-plans"] +} +``` + +A reader who belongs to any audience your site uses is not in `default`. A reader whose only matching group is `beta` sees content tagged `beta` and untagged content, but not content tagged `default`. To show that reader the default content as well, list both: `"audience": ["default", "beta"]`. + +## How readers get an audience + +Readers do not choose an audience. It comes from the `groups` in their user data, which your authentication or personalization method provides when they sign in. See [User data format](/deploy/authentication-setup#user-data-format). + +```json Example user data +{ + "groups": ["internal"], + "expiresAt": 1893456000 +} +``` + +Mintlify keeps only the groups that your site uses as audience tags. With the user data above, the reader is in the `internal` audience. A reader whose groups match no audience tag is in `default`. + +Readers in more than one audience see the content for all of them. A **Viewing as** control in the navbar lets them narrow the view to one audience, or to `default` to see the site as a visitor does. + +## Audiences, groups, and public pages + +`audience` and `groups` use the same names from user data and do different jobs. + +| Property | Controls | Readers outside it | +| :--- | :--- | :--- | +| `groups` | Who can open a page | Receive a 404 | +| `audience` | Who is shown a page | Do not see it in navigation, search, the assistant, or MCP, but can open it by URL | +| `public` | Whether a page requires sign-in | Are asked to sign in | + +The properties combine on one page. An internal page typically carries both `groups` and `audience`: `groups` keeps it private, and `audience` keeps its public counterpart out of internal readers' view. + +```mdx Internal page highlight={3,4} +--- +title: "Feature flags" +audience: internal +groups: ["internal"] +--- +``` + +When a page has both, `groups` is checked first. A reader outside the listed groups receives a 404 regardless of audience. + +## Where audiences apply + +| Surface | Behavior | +| :--- | :--- | +| Navigation | Pages outside the reader's audience are removed. Groups and tabs left empty are removed with them. | +| Search | Results include only pages in the reader's audience and untagged pages. | +| Assistant | Answers draw only on pages in the reader's audience and untagged pages. | +| MCP server | Authenticated sessions return only pages in the reader's audience and untagged pages. Client credentials carry groups, so an agent sees what a reader with those groups sees. | +| `llms.txt` and sitemap | Generated for the reader's audience when the reader is identified, and for the default audience otherwise. | + +## Example + +A site with public product documentation and internal engineering documentation, where the two share a quickstart but each has its own feature flags pages. + +```json docs.json +{ + "navigation": { + "groups": [ + { + "group": "Get started", + "public": true, + "pages": ["index", "quickstart", "authentication"] + }, + { + "group": "Feature flags", + "audience": "default", + "public": true, + "pages": ["platform/feature-flags", "platform/rollouts"] + }, + { + "group": "Feature flags", + "audience": "internal", + "pages": ["internal/feature-flags", "internal/legacy-config"] + }, + { + "group": "Early access", + "audience": ["internal", "beta"], + "pages": ["internal/unreleased"] + } + ] + } +} +``` + +Pages under the `internal` groups also carry `groups: ["internal"]` in frontmatter, and `internal/unreleased` carries `groups: ["internal", "beta"]`. + +| Page | Visitor, not signed in | Reader with `internal` | Reader with `beta` | +| :--- | :--- | :--- | :--- | +| `index`, `quickstart`, `authentication` | Shown | Shown | Shown | +| `platform/feature-flags`, `platform/rollouts` | Shown | Hidden, reachable by URL | Hidden, reachable by URL | +| `internal/feature-flags`, `internal/legacy-config` | 404 | Shown | 404 | +| `internal/unreleased` | 404 | Shown | Shown | + + + Tag every page that has a counterpart in another audience. A page left untagged is shared, so an untagged commercial page would still appear for internal readers next to their own version of it. + diff --git a/create/personalization.mdx b/create/personalization.mdx index 103449479c..d0a71128dd 100644 --- a/create/personalization.mdx +++ b/create/personalization.mdx @@ -138,6 +138,8 @@ Control which pages appear in navigation based on user groups by adding `groups` With personalization, `groups` control visibility but do not restrict access to a page. A visitor can still open a group-filtered page by navigating directly to its URL. Use [authentication](/deploy/authentication-setup) to restrict access to sensitive content. + + `groups` can only add pages to a reader's view. To remove pages from a reader's view, for example to hide public content from internal readers who have their own version of it, use [audiences](/create/audiences). ```mdx diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index 0e5b9eaeaa..54179ddbbb 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -387,6 +387,8 @@ groups: ["admin"] Users must belong to at least one of the listed groups to access the page. If a user tries to access a page without the required group, they'll receive a 404 error. +Groups grant access. To show different groups different content without restricting access, for example a public page and an internal page that share a title, use [audiences](/create/audiences). + ### How groups interact with public pages - All pages require authentication by default. diff --git a/docs.json b/docs.json index 4939acf3d7..df47479742 100644 --- a/docs.json +++ b/docs.json @@ -118,6 +118,7 @@ }, "create/reusable-snippets", "create/personalization", + "create/audiences", { "group": "Editor", "root": "editor/index", diff --git a/organize/navigation.mdx b/organize/navigation.mdx index 54b6b31782..487a595c7a 100644 --- a/organize/navigation.mdx +++ b/organize/navigation.mdx @@ -71,7 +71,7 @@ Use groups to organize your sidebar navigation into sections. You can nest group src="/images/navigation/groups-dark.png" /> -In the `navigation` object, `groups` is an array. Each entry is an object that requires a `group` field and a `pages` field. The `icon`, `tag`, `root`, and `expanded` fields are optional. +In the `navigation` object, `groups` is an array. Each entry is an object that requires a `group` field and a `pages` field. The `icon`, `tag`, `root`, and `expanded` fields are optional. Add an `audience` field to show the group only to readers in that [audience](/create/audiences). ```json { From 032997e3b453c3aea62619da2bdfdc0e3285bc36 Mon Sep 17 00:00:00 2001 From: Justin Torre Date: Thu, 17 Sep 2026 08:59:05 -0700 Subject: [PATCH 2/3] Simplify the audiences page Shorter sections, one idea per sentence, and plainer cross-links. Co-Authored-By: Claude Fable 5.1 --- create/audiences.mdx | 78 +++++++++++++++------------------ create/personalization.mdx | 2 +- deploy/authentication-setup.mdx | 2 +- 3 files changed, 38 insertions(+), 44 deletions(-) diff --git a/create/audiences.mdx b/create/audiences.mdx index 0ea24f850c..07aef763c5 100644 --- a/create/audiences.mdx +++ b/create/audiences.mdx @@ -1,6 +1,6 @@ --- title: "Audiences" -description: "Show each group of readers the content written for them by tagging pages and navigation groups with an audience." +description: "Show each kind of reader the pages written for them by tagging pages and navigation groups with an audience." keywords: ["audience", "audiences", "internal documentation", "groups", "personalization", "hide pages"] --- @@ -8,23 +8,19 @@ keywords: ["audience", "audiences", "internal documentation", "groups", "persona Audiences require [OAuth or JWT authentication](/deploy/authentication-setup), or [personalization](/create/personalization) with JWT or OAuth, on an [Enterprise plan](https://mintlify.com/pricing?ref=audiences). -Audiences let you serve more than one kind of reader from a single site. Tag a page or a navigation group with an audience, and only readers in that audience see it in navigation, search, the assistant, and the MCP server. Everyone else sees the site as if the content were not there. +Audiences let one site serve more than one kind of reader. Tag a page or a navigation group with an audience, and only readers in that audience see it in the sidebar, in search, in the assistant, and through the MCP server. Other readers see the site as if the page were not there. -An audience is named by a group. A reader whose user data includes the group `internal` is in the `internal` audience. There is nothing to declare ahead of time: the group names your identity provider already sends are the audience names you use in your content. +An audience is a group name. A reader whose user data includes the group `internal` is in the `internal` audience. You do not declare audiences anywhere. You use the group names your identity provider already sends. - Audiences control what a reader is shown. They do not control what a reader can access. A page tagged with an audience is still reachable at its URL by anyone who can otherwise open it. To restrict access, use [groups](/deploy/authentication-setup#control-access-with-groups). + Audiences change what a reader sees. They do not change what a reader can open. A tagged page can still be opened by URL by anyone who could open it before. To restrict access, use [groups](/deploy/authentication-setup#control-access-with-groups). -## Tag content with an audience +## Tag a navigation group -Add `audience` to a navigation group in `docs.json` or to a page's frontmatter. The value is a group name or a list of group names. +Add `audience` to a group in `docs.json`. Every page in the group gets that audience unless the page sets its own. -### Navigation groups - -Every page in the group inherits the audience unless it sets its own. - -```json Navigation groups with audiences highlight={6,11} +```json Two groups, one per audience highlight={6,11} { "navigation": { "groups": [ @@ -43,32 +39,32 @@ Every page in the group inherits the audience unless it sets its own. } ``` -Two groups can share a name. A reader in the `internal` audience sees the second group and never the first. Every other reader sees the first group and never the second. The sidebar looks the same to both; the pages behind it differ. +Two groups can have the same name. Readers in the `internal` audience see the second group. Everyone else sees the first. The sidebar looks the same to both readers, and the pages behind it differ. -### Pages +## Tag a page -Set `audience` in frontmatter to tag a single page or to override the audience of its group. +Add `audience` to a page's frontmatter to tag one page or to override its group. -```mdx Page with an audience highlight={3} +```mdx Page with two audiences highlight={3} --- title: "Unreleased features" audience: ["internal", "beta"] --- ``` -A page with more than one audience is shown to readers in any of them. +A page can list more than one audience. Readers in any of them see it. -### Shared content +## Leave shared pages untagged -Content without an `audience` is shown to every reader. Keep quickstarts, authentication guides, and anything else both audiences need untagged, and it appears once, in every reader's view. +Pages without an `audience` appear for everyone. Keep quickstarts, authentication guides, and other shared content untagged. Each appears once, in every reader's view. ## The default audience -`default` is a reserved audience name for readers who belong to none of the audiences your site uses. Every visitor who is not signed in is in the default audience, and so is a signed-in reader whose groups do not match any audience tag on your site. +`default` is a reserved audience name. It means readers who are in none of the audiences your site uses. That includes everyone who is not signed in. -Tag content with `default` to show it only to those readers. This is how you keep a public page out of the view of readers who have their own version of it. +Use it to keep a public page out of the view of readers who have their own version of it. -```json Public content that internal readers should not see highlight={3} +```json Public pages that internal readers should not see highlight={3} { "group": "Billing", "audience": "default", @@ -76,11 +72,11 @@ Tag content with `default` to show it only to those readers. This is how you kee } ``` -A reader who belongs to any audience your site uses is not in `default`. A reader whose only matching group is `beta` sees content tagged `beta` and untagged content, but not content tagged `default`. To show that reader the default content as well, list both: `"audience": ["default", "beta"]`. +A reader in any of your audiences is not in `default`. A reader whose only matching group is `beta` sees `beta` pages and untagged pages, and does not see `default` pages. To show them the `default` pages as well, tag those pages with both audiences, for example `"audience": ["default", "beta"]`. ## How readers get an audience -Readers do not choose an audience. It comes from the `groups` in their user data, which your authentication or personalization method provides when they sign in. See [User data format](/deploy/authentication-setup#user-data-format). +Readers do not pick an audience. When a reader signs in, Mintlify reads the `groups` in their user data and keeps the ones your site uses as audiences. A reader with no matching group is in `default`. See [User data format](/deploy/authentication-setup#user-data-format). ```json Example user data { @@ -89,21 +85,19 @@ Readers do not choose an audience. It comes from the `groups` in their user data } ``` -Mintlify keeps only the groups that your site uses as audience tags. With the user data above, the reader is in the `internal` audience. A reader whose groups match no audience tag is in `default`. - -Readers in more than one audience see the content for all of them. A **Viewing as** control in the navbar lets them narrow the view to one audience, or to `default` to see the site as a visitor does. +Readers in more than one audience see the pages for all of them. A **Viewing as** control in the navbar lets them narrow the view to one audience, or to `default` to see the site as a visitor does. -## Audiences, groups, and public pages +## Audiences and groups together -`audience` and `groups` use the same names from user data and do different jobs. +Both properties use the group names from user data. They do different jobs. -| Property | Controls | Readers outside it | +| Property | What it controls | Readers outside it | | :--- | :--- | :--- | -| `groups` | Who can open a page | Receive a 404 | -| `audience` | Who is shown a page | Do not see it in navigation, search, the assistant, or MCP, but can open it by URL | +| `groups` | Who can open a page | Get a 404 | +| `audience` | Who sees a page in the sidebar, search, assistant, and MCP | Can still open it by URL | | `public` | Whether a page requires sign-in | Are asked to sign in | -The properties combine on one page. An internal page typically carries both `groups` and `audience`: `groups` keeps it private, and `audience` keeps its public counterpart out of internal readers' view. +An internal page usually has both `groups` and `audience`. The first keeps it private. The second keeps its public counterpart out of internal readers' view. ```mdx Internal page highlight={3,4} --- @@ -113,21 +107,21 @@ groups: ["internal"] --- ``` -When a page has both, `groups` is checked first. A reader outside the listed groups receives a 404 regardless of audience. +When a page has both, groups are checked first. A reader outside the listed groups gets a 404 no matter the audience. ## Where audiences apply -| Surface | Behavior | +| Surface | What readers get | | :--- | :--- | -| Navigation | Pages outside the reader's audience are removed. Groups and tabs left empty are removed with them. | -| Search | Results include only pages in the reader's audience and untagged pages. | -| Assistant | Answers draw only on pages in the reader's audience and untagged pages. | +| Navigation | Pages outside the reader's audience are removed. Empty groups and tabs are removed with them. | +| Search | Only pages in the reader's audience and untagged pages. | +| Assistant | Answers based only on pages in the reader's audience and untagged pages. | | MCP server | Authenticated sessions return only pages in the reader's audience and untagged pages. Client credentials carry groups, so an agent sees what a reader with those groups sees. | -| `llms.txt` and sitemap | Generated for the reader's audience when the reader is identified, and for the default audience otherwise. | +| `llms.txt` and sitemap | Built for the reader's audience when the reader is identified, and for `default` otherwise. | ## Example -A site with public product documentation and internal engineering documentation, where the two share a quickstart but each has its own feature flags pages. +A site with public product documentation and internal engineering documentation. The two share a quickstart, and each has its own feature flags pages. ```json docs.json { @@ -159,15 +153,15 @@ A site with public product documentation and internal engineering documentation, } ``` -Pages under the `internal` groups also carry `groups: ["internal"]` in frontmatter, and `internal/unreleased` carries `groups: ["internal", "beta"]`. +Pages under the `internal` groups also have `groups: ["internal"]` in their frontmatter, and `internal/unreleased` has `groups: ["internal", "beta"]`. | Page | Visitor, not signed in | Reader with `internal` | Reader with `beta` | | :--- | :--- | :--- | :--- | | `index`, `quickstart`, `authentication` | Shown | Shown | Shown | -| `platform/feature-flags`, `platform/rollouts` | Shown | Hidden, reachable by URL | Hidden, reachable by URL | +| `platform/feature-flags`, `platform/rollouts` | Shown | Hidden, can open by URL | Hidden, can open by URL | | `internal/feature-flags`, `internal/legacy-config` | 404 | Shown | 404 | | `internal/unreleased` | 404 | Shown | Shown | - Tag every page that has a counterpart in another audience. A page left untagged is shared, so an untagged commercial page would still appear for internal readers next to their own version of it. + Tag every page that has a counterpart in another audience. An untagged page is shared, so internal readers would see an untagged public page next to their own version of it. diff --git a/create/personalization.mdx b/create/personalization.mdx index d0a71128dd..d650151aa0 100644 --- a/create/personalization.mdx +++ b/create/personalization.mdx @@ -139,7 +139,7 @@ Control which pages appear in navigation based on user groups by adding `groups` With personalization, `groups` control visibility but do not restrict access to a page. A visitor can still open a group-filtered page by navigating directly to its URL. Use [authentication](/deploy/authentication-setup) to restrict access to sensitive content. - `groups` can only add pages to a reader's view. To remove pages from a reader's view, for example to hide public content from internal readers who have their own version of it, use [audiences](/create/audiences). + `groups` can only add pages to a reader's view. To remove pages from a reader's view, use [audiences](/create/audiences). ```mdx diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index 54179ddbbb..ac4d6705df 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -387,7 +387,7 @@ groups: ["admin"] Users must belong to at least one of the listed groups to access the page. If a user tries to access a page without the required group, they'll receive a 404 error. -Groups grant access. To show different groups different content without restricting access, for example a public page and an internal page that share a title, use [audiences](/create/audiences). +Groups control access. To show different groups different pages without restricting access, use [audiences](/create/audiences). ### How groups interact with public pages From 787e55290ed3a75e76998d7c802004338bc39f71 Mon Sep 17 00:00:00 2001 From: Justin Torre Date: Thu, 17 Sep 2026 09:03:06 -0700 Subject: [PATCH 3/3] Mark audiences as a closed beta Co-Authored-By: Claude Fable 5.1 --- create/audiences.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/create/audiences.mdx b/create/audiences.mdx index 07aef763c5..812ade8285 100644 --- a/create/audiences.mdx +++ b/create/audiences.mdx @@ -4,6 +4,10 @@ description: "Show each kind of reader the pages written for them by tagging pag keywords: ["audience", "audiences", "internal documentation", "groups", "personalization", "hide pages"] --- + + Audiences are in closed beta. To use them, email [sales@mintlify.com](mailto:sales@mintlify.com). + + Audiences require [OAuth or JWT authentication](/deploy/authentication-setup), or [personalization](/create/personalization) with JWT or OAuth, on an [Enterprise plan](https://mintlify.com/pricing?ref=audiences).