[docs-infra] v8.mui.com

[Janpot]

See https://www.notion.so/mui-org/infra-Backlog-grooming-2026-03-06-31bcbfe7b66080588c2dc5cf271c0562?source=copy_link#31bcbfe7b66080b8baafc84da55c0b94

Tasks:

• Create v8 branch on mui/material-ui-docs
• Configure v8 subdomain to point to v8 branch on Netlify
• Create search index for v8 and wire it up on the v8.x branch
• Create v8.x branch on mui/material-ui Update release instructions to push v7 to material-ui-docs v8
• update publish command on v8.x?
• Make sure X v8 points to v8 search index [docs-infra] Update Release Instructions and Search Index v7 material-ui#48109

[linear]

PUB-201

[dav-is]

To fix search for next.mui.com, I created a new v9 index: mui/material-ui#48028

To prepare for the release, I think we need to:

• sync material-ui v7.x branch with material-ui-docs v7 branch so that v7.mui.com points to v7.3.9 (today it points to v7.0.2)
• create a v8 branch on material-ui-docs to redirect v8.mui.com/material-ui/* to v7.mui.com/material-ui/* (and others) and has a proxy to MUI X's v8 deployment
• update release instructions of v7.x branch to push to both v7 and latest material-ui-docs branches
• rename material-ui index to material-ui-v8 index
• create new crawler MUI_X_V8 that crawls https://v8.mui.com/x/* and https://v7.mui.com/material-ui/* (and others)
  • this should point v8 users to v7 if searching for someone on Material UI
• change v7.x index to use material-ui-v7 index after it has been updated to v7.3.9

One problem is, the index name is defined in the material-ui repo, using the monorepo dependancy. This is probably a good reason to update it to use an environment variable, then we can override it in the v8.x branch in the mui-x repo.

Behavior

When you are on v7.mui.com in the MUI docs and click on an MUI X it should go to v8.mui.com/x/*
When you are on v8.mui.com/x, it should go to v7.mui.com/material-ui/*
When you are on v8.mui.com/material-ui/* it should redirect to v7.mui.com/material-ui/*

After release:

• update release instructions of v7.x branch to push to v7 material-ui-docs branches
• update release instructions of master branch to push to latest material-ui-docs branch (instead of next)
• update MUI_V9 index to crawl https://mui.com (instead of https://next.mui.com
• push master to material-ui-docs branch latest

[Janpot]

Wouldn't it become simpler if we just use single index for all major versions? We can use a single crawler and single index and don't have all this maintenance work when cutting a major. The main thing we'd need to be careful about is to maintain backwards compatibility in our documents. It'd also prevent us from hitting limits in our plan.

[dav-is]

I think most of the complexity here happens because v8 doesn't exist for Material UI (we are skipping v7 to v9). Releasing v10 should be as simple as creating a new crawler and index and bumping the index name (this PR took like 10 minutes: mui/material-ui#48028), then when it's released updating the crawler from next.mui.com to mui.com. Right now we are at 5/20 indexes, so I don't think plan limits are a concern.

I don't think searching previous versions is ever useful, so I don't think an index should contain previous versions.

[dav-is]

After speaking with @mnajdova, she says it is ok for us to deploy Material UI's v7 docs on both v7 and v8 subdomains, which further simplifies this task

[Janpot]

Don't we need a v8 index for MUI X?

[dav-is]

With Marija's suggestion, the v8 index would crawl v8.mui.com which has the content from v7 for material-ui and the content of v8 for mui x

[Janpot]

Right now we are at 5/20 indexes, so I don't think plan limits are a concern.

With an index for v8 that will bring us to 7/20, it's a rise of 10%. While at the same time our indices themselves are tiny. I'd like us to move to a model where we version the index based on document structure, not on lib version. Plan limits are a concern to me, I'd like us having the option to start using Algolia for Base UI as well if we should want to.

this PR took like 10 minutes

From my POV, this PR took at least 2 weeks. I don't want to burden the person that's cutting a major with diving into the implementation details of the search index/crawler, nor do I want them to be blocked on docs infra to pick up this maintenance task. A single index with all versions and the docs app filtering on current version automates all of this. I don't understand the pushback.

[mnajdova]

One last issue with the indexing in algolia, after it is resolved we can close this one. Good work @dav-is

[github-actions]

This issue has been closed. If you have a similar problem but not exactly the same, please open a new issue.
Now, if you have additional information related to this issue or things that could help future readers, feel free to leave a comment.