[docs-infra] JSDoc links are broken about material-ui

[aarongarciah]

Yes, the end goal is to use absolute URLs inside every JSDoc block so devs see the correct URLs in their IDE. But we need to do it in a way that doesn't break URLs that end up in the docs. In the following screenshot, the blue blocks are used to generate part of the docs:

• The first blue block ends up on the API page.
  
• The second blue block ends up in the props table in the API page.
  
• The yellow block is inserted here automatically and AFAIK it's not used to generate any documentation, so it's safe to use absolute URLs there.

If we use absolute URLs in the blue blocks, anytime the docs are built under other base URLs (e.g. PR previews or https://next.mui.com/), they'll point to another domain, which is not what we want.

So the idea is to use absolute URLs in every JSDoc block and adapt the docs generation to replace the https://mui.com base URL with the correct base URL depending on the environment the docs are being built. This requires changes in at least:

• ComponentApiBuilder.ts
• HookApiBuilder.ts

Probably more things need to be adapted, so I'd love someone from @mui/docs-infra to confirm if this approach makes sense before we continue this effort.

[aarongarciah]

@tonygravell sorry, the sandbox was private, you should be able to access it now. I've attached a screenshot to the description.

[tonygravell]

@aarongarciah I'd like to take a look at this issue, but it looks like the codesandbox link is broken for me. Can you give more context on how to reproduce this issue?

[tonygravell]

Would it make sense to make them all use absolute URL's? It looks like some of the links in the file already have them.