mui / mui/material-ui

[docs-infra] Make API links more reliable

Open
#45,452 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

scope: docs-infra
Dominant language
JavaScript
Stars
99.1k
Forks
32.5k
Avg merge
2d 17h
Merged PRs (30d)
106

Description

The links from components pages to API were broken because we rely on the productId of the markdown file to generate them. But they got deleted. We should have a more reliable pipeline, and here are some improvements direction


Things that could be great to do in the future:

  1. Move the markdown location in the file system to match the URL, the mismatch creates a complex routing logic today.
  2. (maybe) normalize the API paths from https://mui.com/x/api/data-grid/ to https://mui.com/x/react-data-grid/api/, simpler but longer URL
  3. In the markdown loader, import getProductInfoFromUrl() to set the productId based on the pathname prefix, so we don't need to repeat productId in the markdown, and more importantly, so any URLs that break the convention can be easily spotted.
  4. Remove the getProductInfoFromUrl() in _app.js so that the productId coming from the markdown can take precedence. Right now, we have to set the productId twice for each page almost in isolation. This is because

Originally posted by @oliviertassinari in https://github.com/mui/mui-x/issues/9573#issuecomment-1621713393

Search keywords:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the markdown loader and _app.js, focusing on how productId and getProductInfoFromUrl() are used to generate API links. Compare the components-page links with the documented API URL patterns. Done means the pipeline no longer depends on deleted markdown productId values and the affected API links resolve reliably.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.