[docs-infra] JSDoc links are broken

[aarongarciah]

Steps to reproduce

Link to live example: https://codesandbox.io/p/sandbox/focused-bardeen-6cw9nz?file=%2Fsrc%2FApp.tsx

Steps:

1. In the code pane of the CodeSandbox linked above, hover the disabled prop in <ListItem disabled />.
2. In the info tooltip, click the ListItemButton link in the @deprecated message.

Current behavior

The link points to "/material-ui/api/list-item-button/" i.e. the link is broken.

Expected behavior

The link should point to "https://mui.com/material-ui/api/list-item-button/".

Context

The docs infra uses JSDoc comments to generate documentation and relative URLs are used for links. The correct URLs are generated in the docs by appending the correct base URL but devs end up with broken links in their IDEs because of the relative URLs.

Your environment

No response

Search keywords: jsdoc, urls

[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?

[aarongarciah]

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

[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.

[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.

[alexfauquette]

Some JSDocs are already using the absolute URL

• in material-ui: https://github.com/mui/material-ui/blob/next/packages/mui-material/src/TextField/TextField.d.ts/#L84-L93
• in the X components: https://github.com/mui/mui-x/blob/master/packages/x-data-grid/src/models/gridExport.ts/#L93-L97

Having working links seems more important than supporting links in preview.

For the next.mui.com we could do a "replace all" with ](https://mui.com when starting the next branch. Ths fix the docs link but also make sure users are redirected to the up to date documentation if they are using the alpha/beta version

[aarongarciah]

Thanks @alexfauquette! @tonygravell let me know if you're still interested in working on this and if you need any help.

[tonygravell]

Okay, let me take a look and I'll reach out if I need be. Thanks!