[docs-infra] Link to API page of components from highlighted code

[eps1lon]

This is just a proof-of-concept.

Links to the API page of a component directly from the highlighted code.
Preview: https://deploy-preview-27393--material-ui.netlify.app/components/pickers/#MaterialUIPickers.tsx

I have some ideas for a way richer syntax highlighting that provides additional information (like an IDE would). Just want to test the waters how the team feels about these type of enhancements.

Though we probably can't go all in right now because it might be too expensive without React 18.

/cc @mui-org/maintainers

[mui-pr-bot]

No bundle size changes (experimental)

Generated by 🚫 dangerJS against cca8210

[oliviertassinari]

I can think of two main areas to dive deeper into:

1. Does it prevent the implementation of live editing? At least, in the shape, it was POC in [docs] Live editable demos #24640?
2. What about the developers that use mouse down to select one example in a demo? It seems to be a bit harder. Should we care? I could find two cases: Developers that start the selection a bit too soon are prevented to select anything by the <a>. Developers that are used to double click on a component name to copy it.

[oliviertassinari]

(I have updated the mui-org/maintainers list to include @danilo-leal. I forgot to include him)

[eps1lon]

What about the developers that use mouse down to select one example in a demo? It seems to be a bit harder. Should we care? I could find two cases: Developers that start the selection a bit too soon are prevented to select anything by the . Developers that are used to double click on a component name to copy it.

These fantastical people you constructed already have problems with selecting any text on the web.

Does it prevent the implementation of live editing? At least, in the shape, it was POC in [docs] Live editable demos #24640?

live editing is still not suitable for documentation. This is another reason why. But I recognize by now if a feature is bought into without justification. Given that I've never seen an actual argument for those, I don't see a value pursuing this.

[siriwatknp]

@eps1lon I think it is nice and worth to try and get feedback from community?. The question is how much the work left to test this feature.

To be honest, I think live editing is too far to reach at this point and if we can improve the current docs with low afford, why not?

[oliviertassinari]

Does it prevent the implementation of live editing?

@eps1lon To continue on my previous comment, sleeping over it. I'm not sure that we need to put live edit and component exploration in opposition. It seems that the answer is no, one doesn't prevent the other:

What if we used the tradeoff that VSCode is using? We could show the component's information on a tooltip when the mouse hovers long enough?

It would also solve the unintended click navigation for the developer's issue I have raised. From what I understand, if we move forward with a direct link, we would be the only documentation that uses this pattern, developers would need to learn it. We also have a challenge around visually communicating that a tag is a link or is not, keeping it with a nice look and with enough contrast.

feature is bought into without justification

I agree. The PR/issue we have about live editing is missing a solid case for why. I have updated #26476 with a Motivation section.

[oliviertassinari]

Reference points:

1. Ariakit https://twitter.com/diegohaz/status/1681277579725090816

It can be tested on https://ariakit.org/guide/getting-started.

2. Nuxt, Another one in the same line of thought: https://nuxt.com/docs/getting-started/seo-meta

Screen.Recording.2024-02-27.at.16.14.10.mov

But poor execution, it's better UX without it.

3. VS Code, it feels like approaching this like VS Code could be a great UX, e.g.

[oliviertassinari]

Moved to a dedicated GitHub issue: #41295.