Skip to content

docs: split Manage your site by job and give reader access its own pages - #8593

Open
ethanpalm wants to merge 5 commits into
mainfrom
docs/manage-site-ia
Open

ethanpalm wants to merge 5 commits into
mainfrom
docs/manage-site-ia

Conversation

@ethanpalm

@ethanpalm ethanpalm commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Applies the job-based IA from the assistant (#8412) and API (#8488) restructures to the "Manage your site" group and the reader authentication docs.

Navigation

"Manage your site" had about 75 pages for four different audiences. It's now five top-level groups:

  • Configure your site: global settings, navigation, visual customization, redirects, .mintignore, contextual menu, narration, bring your own model
  • Deploy and host: deployments and Git providers, CI checks (moved from Create content), repository setup, hosting, export
  • Reader access: an overview, a collapsible Sign-in methods subgroup, then groups, personalization (moved from Create content), and the user data format
  • Analytics: now top-level, with the reports and the two export pages in collapsible Reports and Export subgroups
  • Administer your organization: members, roles, a Security subgroup (SSO, SCIM, session security, network access, audit logs, security contact), personal settings

This separates reader sign-in from dashboard SSO, SCIM, and session security, which used to share one "Authentication" group.

Also:

  • Projects moves to Get started, and Knowledge bases becomes its own top-level group right after Create content, ahead of the sections that only apply to sites.
  • React components and third-party libraries move into a "Custom components" subgroup at the end of Components.

Reader access pages

deploy/authentication-setup had the same shape as the old OpenAPI setup page: four sign-in methods, each with its own prerequisites, setup steps, and example. It's now an overview, and each method has its own page:

  • Overview (same URL): choose a method, make pages public, feature availability, encryption at rest
  • New: Password, Private (organization members only), OAuth 2.0, JWT
  • New: Control access with groups, which says where each method's groups come from and links to the emails domain rules
  • New: User data format, a reference page shared by OAuth, JWT, and personalization

No URLs were removed, so no redirects are needed. English links to the old section anchors now point at the new pages. The overview's Search row also linked to the assistant page, so I fixed that link.

With nested groups collapsed, the Documentation sidebar shows 91 rows, up from 76 on main. Splitting one group into five adds headers, and the subgroups keep the rest of the growth down.

The emails page's groups section is now Assign readers to groups. It keeps per-reader groups and domain rules, and links to the new groups page for the access rules it used to repeat.

Checks

  • mint broken-links: no broken links
  • mint a11y: no issues
  • Vale: new pages are clean; the remaining findings are on lines this PR doesn't touch

Areas of uncertainty

  • deploy/exclude-groups stays hidden because it's in closed beta. The groups page doesn't link to it.
  • The examples now use example.com instead of foo.com, following the style guide's rule on reserved domains.

🤖 Generated with Claude Code


Note

Low Risk
Documentation and navigation only; no application code or authentication behavior changes.

Overview
Reorganizes site-management docs by job and splits reader authentication from one long page into a hub plus focused articles, with navigation in docs.json updated to match.

The former Manage your site section becomes Configure your site, Deploy and host, Reader access, top-level Analytics, and Administer your organization (dashboard SSO/SCIM/security separated from docs sign-in). Projects moves under Get started; Knowledge bases is its own group; Personalization and CI move under Reader access and Deploy respectively.

deploy/authentication-setup is now Control who can read your docs (overview): method comparison with links, public pages, feature availability, and encryption. Setup for password, organization members, OAuth, and JWT lives on new pages; groups and user data format are new shared references. The emails auth page drops duplicated group rules and points at the groups doc.

Cross-links across MCP, analytics, CLI, guides, and page frontmatter now target /deploy/groups, /deploy/user-data-format, and per-method URLs instead of removed authentication-setup anchors (overview anchors like #make-pages-public remain). Minor fixes include the auth overview Search row linking to /optimize/search and examples using example.com domains.

Reviewed by Cursor Bugbot for commit fa2ef68. Bugbot is set up for automated code reviews on this repo. Configure here.

Navigation:
- Replace Manage your site with Configure your site, Deploy and host,
  Reader access, Analytics, and Administer your organization
- Separate reader sign-in from dashboard SSO, SCIM, and session security
- Move CI checks to Deploy and host and personalization to Reader access
- Move Projects to Get started and Knowledge bases to their own group
- Add a Custom components subgroup under Components

Reader access:
- Authentication setup becomes an overview: choose a method, make pages
  public, feature availability, and encryption at rest
- One page each for password, private, OAuth, and JWT authentication
- New Control access with groups and User data format pages
- Point links at the new pages and fix the Search row link

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
Mintlify Docs 🟢 Ready View Preview Nov 19, 2026, 9:54 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@ethanpalm

ethanpalm commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator Author

@mintlify fix merge conflicts

ethanpalm and others added 2 commits November 18, 2026 17:07
# Conflicts:
#	deploy/authentication-setup.mdx
#	docs.json
Splitting the AI group in #8597 dropped its icon, so the two new groups
were the only Guides groups without one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ethanpalm and others added 2 commits November 19, 2026 13:52
- Nest the five sign-in methods under Sign-in methods and the analytics
  pages under Reports and Export, so the sidebar shows 91 rows with
  nested groups collapsed instead of 102
- Move Knowledge bases right after Create content, ahead of the
  site-only sections
- Use the same short method names in the sidebar and the overview
  table: Organization members, Emails
- Rename the emails page's groups section to Assign readers to groups,
  keep only the emails-specific parts, and link to the groups page for
  the access rules

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
staging — fa2ef68f Deployed Nov 19, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant