diff --git a/create/personalization.mdx b/create/personalization.mdx index 103449479..3531fce69 100644 --- a/create/personalization.mdx +++ b/create/personalization.mdx @@ -147,6 +147,18 @@ groups: ["admin"] --- ``` +To hide a page from specific groups instead, use the object form with `excludes`. Users in an excluded group do not see the page in navigation even if they match `includes`. + +```mdx +--- +title: "Customer FAQ" +groups: + - excludes: ["internal"] +--- +``` + +See [Exclude groups](/deploy/authentication-setup#exclude-groups) for the full rules. + ## OpenAPI content filtering Filter API reference content based on user groups with the `x-mint` extension in your OpenAPI specification. You can filter entire endpoints, individual schema properties, `oneOf` variants, and enum values. diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index 0e5b9eaea..821aef89a 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -387,12 +387,67 @@ 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. +### Exclude groups + +To hide a page from specific groups instead of listing every group that can see it, use the object form of `groups` with `includes` and `excludes`. + +```mdx Example page hidden from the internal group highlight={3-4} +--- +title: "Customer FAQ" +groups: + - excludes: ["internal"] +--- +``` + +- `includes`: Groups that can see the page. Omit it to allow every group. An empty list is not allowed; use `groups: []` to deny everyone. +- `excludes`: Groups that cannot see the page, even if they match `includes`. + +A user sees the page when they belong to at least one group in `includes` (or `includes` is omitted) and to no group in `excludes`. Excluded users get a 404 error and do not see the page in navigation, search, or the assistant. + +`excludes` applies only to signed-in users. Visitors who are not signed in have no groups, so a page with `public: true` and `excludes` is visible to everyone except signed-in members of the excluded groups. Combine `public` with `excludes` to publish a page to the world while hiding it from an internal team. + + + +```mdx Everyone except internal +--- +title: "Customer FAQ" +public: true +groups: + - excludes: ["internal"] +--- +``` + +```mdx Internal only, also public +--- +title: "Release notes" +public: true +groups: + - includes: ["internal"] +--- +``` + +```mdx Internal only, sign-in required +--- +title: "Runbook" +groups: + - includes: ["internal"] +--- +``` + + +With the three pages above, a visitor who is not signed in sees the Customer FAQ and Release notes. A signed-in member of `internal` sees Release notes and the Runbook. + + + The `*` wildcard is not allowed in `excludes`. To hide a page from all signed-in users, set `groups: []`. + + ### How groups interact with public pages - All pages require authentication by default. - Pages with a `groups` property are only accessible to authenticated users in those groups. - Pages without a `groups` property are accessible to all authenticated users. - Pages with `public: true` and no `groups` property are accessible to everyone. +- Pages with `public: true` and `excludes` are accessible to everyone except signed-in users in the excluded groups. @@ -415,6 +470,15 @@ title: "Advanced configurations" groups: ["pro", "enterprise"] --- ``` + +```mdx Public page hidden from a group +--- +title: "Customer FAQ" +public: true +groups: + - excludes: ["internal"] +--- +``` ## User data format